@tpsdev-ai/flair 0.25.4 → 0.26.0

package/dist/cli.js

@@ -6432,6 +6432,12 @@ remNightly
         if (row.candidates) {
             console.log(`Staged:     ${row.candidates.length} candidate${row.candidates.length === 1 ? "" : "s"}`);
         }
+        // row.dedup populates when step 6 (instance-wide dedup-cluster stat,
+        // flair-quality Slice 1c) succeeded this cycle. Absent on dry-run skip
+        // or a non-fatal failure (see Errors below — e.g. non-admin caller).
+        if (row.dedup) {
+            console.log(`Dedup:      ${row.dedup.clusterCount} cluster${row.dedup.clusterCount === 1 ? "" : "s"} (${row.dedup.totalMemoriesInClusters} memories, largest ${row.dedup.largestClusterSize})`);
+        }
         console.log(`Duration:   ${row.durationMs}ms`);
         if (row.errors.length > 0) {
             console.log(`Errors:`);
@@ -10148,6 +10154,564 @@ program
     if (summary.exitCode !== 0)
         process.exit(summary.exitCode);
 });
+// ─── flair quality — pure metric computation ─────────────────────────────────
+// Slice 1a of the memory-quality-observability arc (ops/proposals/
+// flair-quality-slice1-spec.md, K&S design-approved). Same "extract the pure
+// decision logic" idiom as summarizeDoctorRun above (flair#721) and
+// derivePresenceStatus (resources/Presence.ts): the CLI action spawns a
+// network fetch + a long console.log sequence, which is high-effort/
+// low-value to drive directly in a test — this is the actual metric math,
+// fed a fixture-shaped /HealthDetail body.
+//
+// ZERO new server surface. Every field this reads already exists in
+// resources/health.ts's response (the same one `flair status`/`flair doctor`
+// consume) — no new query pattern, no new endpoint. That's what makes the
+// Sherlock "read-scope holds by construction" argument hold: quality can
+// never see anything status/doctor couldn't already see, because it reads
+// the identical payload.
+//
+// One metric from the design doc is deliberately NOT computed at full
+// fidelity here — it degrades gracefully into a `gaps` entry instead of
+// failing:
+//   - staleness: /HealthDetail's `memories.expired` count is instance-wide
+//     only (resources/health.ts never buckets it per agent), so --agent
+//     does not scope this metric. The "old + never-recalled" variant isn't
+//     computed at all — no read API exposes per-memory last-recalled data.
+//
+// Slice 1b (flair-quality-slice1b): signal density now ALSO carries citation
+// rate. Kern's design nod: extend /HealthDetail's per-agent aggregation
+// server-side (resources/health.ts sums Memory.usageCount — a field already
+// loaded by the existing memory loop, no new query) rather than have the CLI
+// join against `GET /Memory` itself — keeps quality's read footprint
+// identical to status/doctor's by construction. `citationRate` here is
+// computed CLI-side from the two numbers the server hands back
+// (usageCount/memoryCount), same "server aggregates, CLI computes" split as
+// every other metric in this file.
+//
+// Backward compatibility: an OLDER server's /HealthDetail predates
+// per-agent `usageCount` entirely (field is `undefined` on the row, not
+// `0` — Slice 1a's payload literally didn't have the key). That's detected
+// per-row and the whole report degrades to the Slice-1a write-volume-only
+// shape + a gap note, rather than silently reporting citationRate 0 as if
+// it were real data from a server that never sent it.
+//
+// Naming (Sherlock security finding on the design round, reaffirmed for
+// citation rate): "signal density" / "citation rate" describes a USAGE
+// PATTERN, never a trust/quality verdict. A low citation rate means "writes
+// exploratory content that's rarely cited", not "noisy" or "untrustworthy"
+// — same for "quiet agents": an ops fact (days since last write), not a
+// trust signal. Keep that framing in any copy touching this code.
+//
+// Slice 1c (flair-quality-slice1c-dedup-spec.md, K&S-resolved to "Option C,
+// server-side"): dedup-cluster count — how many near-duplicate memory
+// CLUSTERS exist instance-wide. Sherlock's hard security line: embeddings
+// are the most sensitive data in the system and must never leave the
+// server, so — unlike every other metric in this file — the computation
+// does NOT happen here. A nightly server-side REM step
+// (resources/MemoryDedupStats.ts, wired into src/rem/runner.ts) computes it
+// server-side via a bounded-k ANN sweep (reusing the HNSW-backed retrieval
+// core) and persists ONLY the aggregate `{clusterCount, largestClusterSize,
+// totalMemoriesInClusters, computedAt}` to a small server-side stat file.
+// /HealthDetail does a CHEAP read of that file (resources/health.ts) —
+// still zero new query pattern from the CLI's perspective, same "quality
+// reads a precomputed number from /HealthDetail" contract as every other
+// metric here. Nightly-stale by construction (only as fresh as the last
+// REM cycle) — that's an accepted trade-off, not a bug: it's a "silting up"
+// trend signal, not a real-time alert. Absent (fresh instance, REM never
+// run, or an older server) degrades to `null` + a `gaps` entry, never a
+// false zero.
+//
+// Slice 1d (memory-quality arc, self-referential design — no hardcoded canned
+// queries): recall SPOT-CHECK. Unlike every metric above, this ISN'T read
+// from /HealthDetail at all — it's the one metric in this file that requires
+// live QUERIES, because it's checking whether querying itself still works.
+// For a sample of the querying agent's OWN memories (fetchRecallSpotCheckData
+// below, GET /Memory?agentId=<self>), a CUE is derived from each memory
+// (deriveRecallCue — its `subject` if present, else the leading ~8 words /
+// first sentence of `content`; a PARTIAL cue, never the full content) and
+// searched for through the EXACT SAME authenticated read path `flair memory
+// search` uses: `api("POST", "/SemanticSearch", ...)`, which resolves auth
+// via the shared authedRequest() 5-tier resolver (src/lib/auth-resolve.ts) —
+// identical code path, so read-scope holds by construction (no new
+// endpoint, no cross-agent/private data, scoped to the querying agent's own
+// memories same as `flair memory search` always was). computeRecallSpotCheck
+// (below) is the pure scorer: recall@k = fraction of sampled memories whose
+// own id appears in its search's top-k; MRR = mean reciprocal rank (0 if
+// not found within k).
+//
+// Framing — this is a HEALTH SPOT-CHECK, not a benchmark and not a trust
+// judgment. Querying by a cue derived FROM the target memory is easier than
+// a real user query, so a high score means "recall is functioning", not
+// "recall is optimal". Its job is to catch recall CRATERING (embeddings
+// down, index busted) — the score collapsing toward 0 is the signal, not
+// fine-grained precision grading. Requires an actual agent identity to
+// query AS (semantic search is agent-scoped) — no identity, fewer than the
+// sample-size memories to sample, or a search error all degrade to `null` +
+// a `gaps` entry, same graceful-degradation contract as every metric here —
+// NEVER a false 0.0 masquerading as a real (broken) score.
+/** First-pass default, same "documented heuristic, not derived from data we
+ *  don't have" spirit as health.ts's own 10%-hash-fallback threshold below.
+ *  Tunable later if a real fleet shows this is too loud/quiet. */
+export const QUALITY_QUIET_THRESHOLD_DAYS = 7;
+/** Mirrors resources/health.ts's own hash-fallback warning threshold (kept as
+ *  a literal constant here rather than imported — health.ts computes its
+ *  warning string server-side, this recomputes the same judgment CLI-side
+ *  from the raw counts so quality doesn't depend on parsing warning text). */
+export const QUALITY_HASH_FALLBACK_DEGRADED_PCT = 10;
+/** Recall spot-check (Slice 1d) defaults — how many of the querying agent's
+ *  own memories to sample, and the top-k depth each is searched at. Same
+ *  "first-pass default, tunable later" spirit as the thresholds above. */
+export const QUALITY_RECALL_SAMPLE_SIZE = 10;
+export const QUALITY_RECALL_K = 5;
+/**
+ * Derive a PARTIAL search cue from a memory — used by the recall spot-check
+ * (Slice 1d) to query for a memory without handing back its full content.
+ * Prefers `subject` when present and non-trivial (a real word or phrase, not
+ * empty/whitespace-only padding); otherwise falls back to the first sentence
+ * of `content`, capped to the leading ~8 words so the cue stays a genuine
+ * partial cue rather than the whole memory. Pure — no I/O.
+ */
+export function deriveRecallCue(memory) {
+    const subject = (memory.subject ?? "").trim();
+    if (subject.length >= 3)
+        return subject;
+    const content = (memory.content ?? "").trim();
+    if (!content)
+        return "";
+    const sentenceMatch = content.match(/^[^.!?\n]+[.!?]?/);
+    const firstSentence = (sentenceMatch ? sentenceMatch[0] : content).trim();
+    const words = firstSentence.split(/\s+/).filter(Boolean);
+    const cueWordLimit = 8;
+    return words.length <= cueWordLimit ? firstSentence : words.slice(0, cueWordLimit).join(" ");
+}
+/**
+ * Pure scorer for the recall spot-check (Slice 1d): given the ids of the
+ * sampled memories and, for each, the list of memory ids its derived-cue
+ * search returned (already agent-scoped via the same read path `flair
+ * memory search` uses), compute recall@k + MRR. `perQueryResultIds[i]` is
+ * truncated to the first `k` entries here (not assumed pre-truncated by the
+ * caller) so a caller that over-fetches still gets a correct top-k score.
+ * Never throws; an empty sample scores 0/0 rather than dividing by zero —
+ * callers are expected to treat an empty sample as a `gaps` case, not a
+ * real 0.0 score (see fetchRecallSpotCheckData / computeQualityReport).
+ */
+export function computeRecallSpotCheck(sampledIds, perQueryResultIds, k) {
+    const sampleSize = sampledIds.length;
+    if (sampleSize === 0) {
+        return { recallAtK: 0, mrr: 0, sampleSize: 0, k };
+    }
+    let hits = 0;
+    let reciprocalSum = 0;
+    for (let i = 0; i < sampleSize; i++) {
+        const targetId = sampledIds[i];
+        const topK = (perQueryResultIds[i] ?? []).slice(0, k);
+        const rank = topK.indexOf(targetId);
+        if (rank !== -1) {
+            hits += 1;
+            reciprocalSum += 1 / (rank + 1);
+        }
+    }
+    return {
+        recallAtK: Math.round((hits / sampleSize) * 100) / 100,
+        mrr: Math.round((reciprocalSum / sampleSize) * 100) / 100,
+        sampleSize,
+        k,
+    };
+}
+/**
+ * Pure computation: /HealthDetail response (+ reachability) → quality report.
+ * Never throws — every missing data source degrades to a null section + a
+ * `gaps` entry (same graceful-degradation contract as `flair doctor`), so a
+ * partially-populated instance still gets a partial, honest report instead
+ * of a crash.
+ *
+ * `opts.recallSpotCheckData` is the ONE exception to "fed purely from
+ * /HealthDetail": the recall spot-check (Slice 1d) requires live queries
+ * (fetchRecallSpotCheckData, run by the `quality` command BEFORE calling
+ * here, same "I/O happens outside, this function only computes" split as
+ * fetchHealthDetail/computeQualityReport itself). Passing nothing degrades
+ * to a `gaps` entry, same as every other metric.
+ */
+export function computeQualityReport(healthy, healthData, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const agentFilter = opts.agentId ?? null;
+    const gaps = [];
+    // ── Instance health: migrations ──
+    let migrationsClean = null;
+    let haltedMigrations = [];
+    const migList = healthData?.migrations?.migrations;
+    if (Array.isArray(migList)) {
+        haltedMigrations = migList
+            .filter((m) => m?.state === "halted" || m?.state === "failed")
+            .map((m) => ({ id: m.id, state: m.state, reason: m.reason }));
+        migrationsClean = haltedMigrations.length === 0;
+    }
+    else {
+        gaps.push({ metric: "instance.migrationsClean", reason: "no migrations block in /HealthDetail response" });
+    }
+    // ── Instance health: embeddings operational ──
+    // Inferred from stored coverage stats (hash-fallback %, mixed embedding
+    // models) — NOT a live semantic round-trip like `flair doctor` runs
+    // (verifySemanticSearch writes a probe memory to verify recall-by-meaning,
+    // which this read-only command must not do).
+    let embeddingsStatus = "unknown";
+    let embeddingsDetail = "no memory stats available";
+    const memories = healthData?.memories;
+    if (memories && typeof memories.total === "number") {
+        if (memories.total === 0) {
+            embeddingsDetail = "no memories written yet";
+        }
+        else {
+            const hashFallback = memories.hashFallback ?? 0;
+            const pct = Math.round((hashFallback / memories.total) * 100);
+            const modelCounts = (memories.modelCounts ?? {});
+            const realModels = Object.keys(modelCounts).filter((k) => k !== "hash-512d" && modelCounts[k] > 0);
+            if (pct >= QUALITY_HASH_FALLBACK_DEGRADED_PCT) {
+                embeddingsStatus = "degraded";
+                embeddingsDetail = `${hashFallback}/${memories.total} (${pct}%) memories are hash-fallback`;
+            }
+            else if (realModels.length > 1) {
+                embeddingsStatus = "degraded";
+                embeddingsDetail = `multiple embedding models in use (${realModels.join(", ")}) — cross-model search unreliable`;
+            }
+            else {
+                embeddingsStatus = "ok";
+                embeddingsDetail = `${memories.total - hashFallback}/${memories.total} memories have real embeddings`;
+            }
+        }
+    }
+    // ── Embedding coverage ──
+    let embeddingCoverage = null;
+    if (memories && typeof memories.total === "number") {
+        const total = memories.total;
+        const hashFallback = memories.hashFallback ?? 0;
+        const withEmbeddings = typeof memories.withEmbeddings === "number" ? memories.withEmbeddings : Math.max(0, total - hashFallback);
+        const coveragePct = total > 0 ? Math.round((withEmbeddings / total) * 100) : 0;
+        embeddingCoverage = { total, withEmbeddings, hashFallback, coveragePct };
+    }
+    else {
+        gaps.push({ metric: "embeddingCoverage", reason: "no memory stats available in /HealthDetail response" });
+    }
+    // ── Staleness (instance-wide only — see module doc above) ──
+    let staleness = null;
+    if (memories && typeof memories.total === "number" && typeof memories.expired === "number") {
+        const total = memories.total;
+        const expired = memories.expired;
+        const stalePct = total > 0 ? Math.round((expired / total) * 100) : 0;
+        staleness = { scope: "instance", total, expired, stalePct };
+        gaps.push({
+            metric: "staleness",
+            reason: "instance-wide only — /HealthDetail's `expired` count isn't broken down per agent, so --agent doesn't scope this metric; the \"old + never-recalled\" dead-weight variant also isn't computed (no read API exposes per-memory last-recalled data)",
+        });
+    }
+    else {
+        gaps.push({ metric: "staleness", reason: "no expired-memory count available in /HealthDetail response" });
+    }
+    // ── Per-agent rows (shared source for signal density + quiet agents) ──
+    const perAgentAll = Array.isArray(healthData?.agents?.perAgent) ? healthData.agents.perAgent : [];
+    const havePerAgent = Array.isArray(healthData?.agents?.perAgent);
+    const scopedAgents = agentFilter ? perAgentAll.filter((r) => r.id === agentFilter) : perAgentAll;
+    // Detected from the UNFILTERED rows (not scopedAgents) so `--agent` never
+    // masquerades server capability as data-scoping — vacuously true on an
+    // empty perAgent array (nothing to prove otherwise, and both scopes render
+    // identically empty either way).
+    const haveUsageCount = perAgentAll.every((r) => typeof r.usageCount === "number");
+    // ── Signal density (write volume, + citation rate when the server supports it) ──
+    let signalDensity = null;
+    if (havePerAgent && haveUsageCount) {
+        signalDensity = {
+            scope: "write-and-citation",
+            perAgent: scopedAgents.map((r) => {
+                const usageCount = r.usageCount ?? 0;
+                const citationRate = r.memoryCount > 0 ? Math.round((usageCount / r.memoryCount) * 100) / 100 : 0;
+                return { id: r.id, memoryCount: r.memoryCount, writes24h: r.writes24h, lastWriteAt: r.lastWriteAt, usageCount, citationRate };
+            }),
+        };
+    }
+    else if (havePerAgent) {
+        signalDensity = {
+            scope: "write-volume",
+            perAgent: scopedAgents.map((r) => ({ id: r.id, memoryCount: r.memoryCount, writes24h: r.writes24h, lastWriteAt: r.lastWriteAt })),
+        };
+        gaps.push({
+            metric: "signalDensity",
+            reason: "citation rate unavailable — server predates per-agent usageCount in /HealthDetail; upgrade the server",
+        });
+    }
+    else {
+        gaps.push({ metric: "signalDensity", reason: "no per-agent stats available in /HealthDetail response" });
+    }
+    // ── Quiet agents (ops fact — not a trust signal) ──
+    let quietAgents = null;
+    if (havePerAgent) {
+        const rows = scopedAgents.map((r) => {
+            const daysSinceLastWrite = r.lastWriteAt ? Math.floor((now - new Date(r.lastWriteAt).getTime()) / 86_400_000) : null;
+            const quiet = daysSinceLastWrite === null ? true : daysSinceLastWrite >= QUALITY_QUIET_THRESHOLD_DAYS;
+            return { id: r.id, memoryCount: r.memoryCount, writes24h: r.writes24h, lastWriteAt: r.lastWriteAt, daysSinceLastWrite, quiet };
+        });
+        quietAgents = { thresholdDays: QUALITY_QUIET_THRESHOLD_DAYS, perAgent: rows, quietCount: rows.filter((r) => r.quiet).length };
+    }
+    else {
+        gaps.push({ metric: "quietAgents", reason: "no per-agent stats available in /HealthDetail response" });
+    }
+    // ── Dedup clusters (instance-wide near-duplicate count — flair-quality
+    // Slice 1c) — an ops/health signal, not a trust judgment (see module doc
+    // and QualityReport['dedupClusters'] doc above). Always instance-wide;
+    // --agent does not scope it (matches staleness's precedent — the
+    // underlying stat has no per-agent breakdown, by design: per-memory
+    // cluster membership is a disclosure surface Sherlock's review explicitly
+    // ruled out storing at all).
+    let dedupClusters = null;
+    const dedup = healthData?.dedup;
+    if (dedup &&
+        typeof dedup.clusterCount === "number" &&
+        typeof dedup.largestClusterSize === "number" &&
+        typeof dedup.totalMemoriesInClusters === "number" &&
+        typeof dedup.computedAt === "string") {
+        dedupClusters = {
+            clusterCount: dedup.clusterCount,
+            largestClusterSize: dedup.largestClusterSize,
+            totalMemoriesInClusters: dedup.totalMemoriesInClusters,
+            computedAt: dedup.computedAt,
+        };
+    }
+    else {
+        gaps.push({
+            metric: "dedupClusters",
+            reason: "no dedup-cluster stat yet — computed nightly by REM (see `flair rem nightly enable`); run `flair rem nightly run-once` or wait for the first scheduled cycle",
+        });
+    }
+    // ── Recall spot-check (flair-quality Slice 1d) — see module doc above and
+    // QualityReport['recallSpotCheck'] doc for the full framing. Fed by
+    // fetchRecallSpotCheckData's already-fetched raw ids (not by healthData —
+    // this is the one metric here that needed a live query, not a
+    // /HealthDetail read); scored by the pure computeRecallSpotCheck.
+    let recallSpotCheck = null;
+    const rsc = opts.recallSpotCheckData;
+    if (rsc?.ok && rsc.sampledIds && rsc.perQueryResultIds && typeof rsc.k === "number") {
+        const scored = computeRecallSpotCheck(rsc.sampledIds, rsc.perQueryResultIds, rsc.k);
+        recallSpotCheck = { agentId: rsc.agentId ?? agentFilter ?? null, ...scored };
+    }
+    else {
+        gaps.push({
+            metric: "recallSpotCheck",
+            reason: rsc?.skipReason ?? "recall spot-check not attempted — no data passed to computeQualityReport",
+        });
+    }
+    return {
+        agentFilter,
+        instance: { up: healthy, migrationsClean, haltedMigrations, embeddingsStatus, embeddingsDetail },
+        embeddingCoverage,
+        staleness,
+        signalDensity,
+        quietAgents,
+        dedupClusters,
+        recallSpotCheck,
+        gaps,
+    };
+}
+/**
+ * The I/O half of the recall spot-check (Slice 1d): fetch a sample of
+ * `agentId`'s own memories and, for each, search for a cue derived from it.
+ * Reuses the EXACT read path `flair memory search` / `flair memory list`
+ * use — `api()` (→ authedRequest's 5-tier resolver) for both the
+ * `GET /Memory?agentId=...` sample fetch and the `POST /SemanticSearch`
+ * queries — so this has zero new endpoint and zero new auth mechanism; it
+ * is scoped to `agentId`'s own memories exactly as those commands already
+ * are. Never throws: every failure mode (no agentId, fewer than
+ * `sampleSize` memories, a fetch/search error) returns `{ ok: false,
+ * skipReason }` for computeQualityReport to turn into a `gaps` entry.
+ */
+async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
+    const sampleSize = opts.sampleSize ?? QUALITY_RECALL_SAMPLE_SIZE;
+    const k = opts.k ?? QUALITY_RECALL_K;
+    if (!agentId) {
+        return { ok: false, skipReason: "no agent identity to query as — pass --agent or set FLAIR_AGENT_ID" };
+    }
+    let all;
+    try {
+        const q = new URLSearchParams({ agentId }).toString();
+        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl });
+        all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
+    }
+    catch (err) {
+        return { ok: false, agentId, skipReason: `could not fetch memories to sample: ${err?.message ?? String(err)}` };
+    }
+    if (all.length < sampleSize) {
+        return {
+            ok: false,
+            agentId,
+            skipReason: `agent '${agentId}' has ${all.length} memories, fewer than the ${sampleSize} needed to sample`,
+        };
+    }
+    // Deterministic sample: the sampleSize most-recently-written memories.
+    const sorted = all.slice().sort((a, b) => {
+        const ta = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const tb = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return tb - ta;
+    });
+    const sampled = sorted.slice(0, sampleSize);
+    const sampledIds = [];
+    const perQueryResultIds = [];
+    try {
+        for (const m of sampled) {
+            const id = String(m.id);
+            const cue = deriveRecallCue(m);
+            const body = { agentId, q: cue, limit: k };
+            const res = await api("POST", "/SemanticSearch", body, { baseUrl });
+            const results = Array.isArray(res) ? res : (res?.results ?? []);
+            sampledIds.push(id);
+            perQueryResultIds.push(results.map((r) => String(r.id)));
+        }
+    }
+    catch (err) {
+        return { ok: false, agentId, skipReason: `recall spot-check search failed: ${err?.message ?? String(err)}` };
+    }
+    return { ok: true, agentId, sampledIds, perQueryResultIds, k };
+}
+// ─── flair quality ────────────────────────────────────────────────────────────
+program
+    .command("quality")
+    .description("Memory-quality report: embedding coverage, staleness, signal density, quiet agents, recall spot-check (read-only)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
+    .option("--json", "Output as JSON")
+    .option("--agent <id>", "Scope per-agent metrics to one agent id (or set FLAIR_AGENT_ID); default = all agents")
+    .action(async (opts) => {
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts);
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID || null;
+    // Recall spot-check needs live queries (not just /HealthDetail), so only
+    // attempt it when the instance is actually reachable — no point probing
+    // memory reads against a server fetchHealthDetail already found down.
+    const recallSpotCheckData = healthy
+        ? await fetchRecallSpotCheckData(agentId, baseUrl)
+        : { ok: false, skipReason: "instance unreachable" };
+    const report = computeQualityReport(healthy, healthData, { agentId, recallSpotCheckData });
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        const out = { healthy, url: baseUrl, flairVersion: __pkgVersion, ...report };
+        console.log(render.asJSON(out));
+        if (!healthy)
+            process.exit(1);
+        return;
+    }
+    if (!healthy) {
+        console.log(`Flair v${__pkgVersion} — 🔴 unreachable`);
+        console.log(`  URL:  ${baseUrl}`);
+        console.log(`\n  Run: flair start  or  flair doctor`);
+        process.exit(1);
+    }
+    const scopeLabel = agentId ? ` ${render.wrap(render.c.dim, `(agent: ${agentId})`)}` : "";
+    console.log(`${render.wrap(render.c.bold, "Flair quality report")}${scopeLabel}`);
+    console.log(render.kv("URL", baseUrl));
+    // Instance health
+    console.log(`\n${render.wrap(render.c.bold, "Instance health")}`);
+    console.log(render.kv("Up", report.instance.up ? `${render.icons.ok} yes` : `${render.icons.error} no`));
+    if (report.instance.migrationsClean === null) {
+        console.log(render.kv("Migrations", `${render.icons.info} unknown ${render.wrap(render.c.dim, "(no data)")}`));
+    }
+    else if (report.instance.migrationsClean) {
+        console.log(render.kv("Migrations", `${render.icons.ok} clean`));
+    }
+    else {
+        console.log(render.kv("Migrations", `${render.icons.error} ${report.instance.haltedMigrations.length} halted/failed`));
+        for (const m of report.instance.haltedMigrations) {
+            console.log(`    ${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
+        }
+    }
+    const embIcon = report.instance.embeddingsStatus === "ok" ? render.icons.ok :
+        report.instance.embeddingsStatus === "degraded" ? render.icons.error :
+            render.icons.info;
+    console.log(render.kv("Embeddings", `${embIcon} ${report.instance.embeddingsStatus} ${render.wrap(render.c.dim, `(${report.instance.embeddingsDetail})`)}`));
+    // Embedding coverage
+    if (report.embeddingCoverage) {
+        const ec = report.embeddingCoverage;
+        console.log(`\n${render.wrap(render.c.bold, "Embedding coverage")}`);
+        console.log(render.kv("Coverage", `${render.wrap(render.c.bold, `${ec.coveragePct}%`)} ${render.wrap(render.c.dim, `(${ec.withEmbeddings}/${ec.total} real, ${ec.hashFallback} hash-fallback)`)}`));
+    }
+    // Staleness
+    if (report.staleness) {
+        const st = report.staleness;
+        console.log(`\n${render.wrap(render.c.bold, "Staleness")}`);
+        console.log(render.kv("Past validTo", `${render.wrap(render.c.bold, `${st.stalePct}%`)} ${render.wrap(render.c.dim, `(${st.expired}/${st.total}, instance-wide)`)}`));
+    }
+    // Signal density
+    if (report.signalDensity) {
+        console.log(`\n${render.wrap(render.c.bold, "Signal density")} ${render.wrap(render.c.dim, "(write + citation activity — a usage pattern, not a trust signal)")}`);
+        if (agentId && report.signalDensity.perAgent.length === 0) {
+            console.log(`  ${render.icons.info} no data for agent '${agentId}'`);
+        }
+        else {
+            const showCitation = report.signalDensity.scope === "write-and-citation";
+            const cols = [
+                { label: "id", key: "id" },
+                { label: "memories", key: "memoryCount", align: "right" },
+                { label: "writes_24h", key: "writes24h", align: "right" },
+                ...(showCitation
+                    ? [
+                        { label: "citations", key: "usageCount", align: "right" },
+                        { label: "citation_rate", key: "citationRate", align: "right" },
+                    ]
+                    : []),
+                { label: "last_write", key: "lastWriteAt", format: (v) => render.relativeTime(v) },
+            ];
+            console.log(render.table(cols, report.signalDensity.perAgent));
+            if (showCitation) {
+                console.log(`  ${render.wrap(render.c.dim, "citation_rate = avg citations per memory; a low rate means \"writes exploratory content that's rarely cited\", not \"noisy\"")}`);
+            }
+            else {
+                console.log(`  ${render.wrap(render.c.dim, "citation rate not shown — server predates per-agent usageCount in /HealthDetail (see Gaps); low write volume means \"writes exploratory content\", not \"noisy\"")}`);
+            }
+        }
+    }
+    // Quiet agents
+    if (report.quietAgents) {
+        console.log(`\n${render.wrap(render.c.bold, "Quiet agents")} ${render.wrap(render.c.dim, `(no write in ${report.quietAgents.thresholdDays}+ days — an ops fact, not a trust signal)`)}`);
+        if (agentId && report.quietAgents.perAgent.length === 0) {
+            console.log(`  ${render.icons.info} no data for agent '${agentId}'`);
+        }
+        else {
+            const quiet = report.quietAgents.perAgent.filter((r) => r.quiet);
+            if (quiet.length === 0) {
+                console.log(`  ${render.icons.ok} none`);
+            }
+            else {
+                for (const r of quiet) {
+                    const label = r.daysSinceLastWrite == null ? "never written" : `quiet for ${r.daysSinceLastWrite}d`;
+                    console.log(`  ${render.icons.warn} ${r.id} — ${label}`);
+                }
+            }
+        }
+    }
+    // Dedup clusters (flair-quality Slice 1c) — an ops/health signal, not a
+    // trust judgment. Labeled with the nightly REM run that produced it, per
+    // spec, since it's only ever as fresh as the last nightly cycle.
+    if (report.dedupClusters) {
+        const dc = report.dedupClusters;
+        console.log(`\n${render.wrap(render.c.bold, "Dedup clusters")} ${render.wrap(render.c.dim, `(as of last REM run ${render.relativeTime(dc.computedAt)}, ${dc.computedAt})`)}`);
+        console.log(render.kv("Clusters", `${render.wrap(render.c.bold, String(dc.clusterCount))} ${render.wrap(render.c.dim, `(${dc.totalMemoriesInClusters} memories, largest cluster ${dc.largestClusterSize})`)}`));
+        console.log(`  ${render.wrap(render.c.dim, "an ops signal — near-duplicate memories piling up, not a trust judgment")}`);
+    }
+    // Recall spot-check (flair-quality Slice 1d) — a health SPOT-CHECK, not
+    // a benchmark or trust judgment: catches recall cratering (embeddings/
+    // index down), not a quality grade. See QualityReport['recallSpotCheck']
+    // doc for the full framing.
+    if (report.recallSpotCheck) {
+        const rc = report.recallSpotCheck;
+        console.log(`\n${render.wrap(render.c.bold, "Recall spot-check")} ${render.wrap(render.c.dim, `(agent ${rc.agentId ?? "—"}, health signal — not a benchmark)`)}`);
+        console.log(render.kv(`recall@${rc.k}`, `${render.wrap(render.c.bold, rc.recallAtK.toFixed(2))} ${render.wrap(render.c.dim, `(MRR ${rc.mrr.toFixed(2)}, ${rc.sampleSize} sampled)`)}`));
+        console.log(`  ${render.wrap(render.c.dim, "catches recall cratering (embeddings/index down) — a high score means recall is functioning, not that it's optimal")}`);
+    }
+    // Gaps
+    if (report.gaps.length > 0) {
+        console.log(`\n${render.wrap(render.c.bold, "Gaps")} ${render.wrap(render.c.dim, "(degraded or unavailable from existing read APIs)")}`);
+        for (const g of report.gaps) {
+            console.log(`  ${render.icons.info} ${g.metric}: ${g.reason}`);
+        }
+    }
+    console.log("");
+});
 // ─── flair session snapshot ──────────────────────────────────────────────────
 // Slice 2 of FLAIR-AGENT-CONTEXT-TIERS-B. Snapshot a
 // session jsonl + label metadata into a tar.gz under ~/.flair/snapshots/<agent>/sessions/.

package/dist/rem/runner.js

@@ -8,7 +8,13 @@
  *   4. Trust-tier filter on input memories — permanently deferred (see below).
  *   5. Distillation — call /ReflectMemories with execute:true, persist staged
  *      candidate ids to the audit row.
- *   6. Append a row to ~/.flair/logs/rem-nightly.jsonl.
+ *   6. Instance-wide dedup-cluster stat — call /MemoryDedupStats (flair-
+ *      quality Slice 1c). NOT part of FLAIR-NIGHTLY-REM's original per-agent
+ *      § 4 list — added because a near-duplicate cluster count is inherently
+ *      instance-wide (dupes across agents matter), so it runs once per cycle
+ *      after the per-agent passes above, rather than being scoped to
+ *      opts.agentId like everything else in this file.
+ *   7. Append a row to ~/.flair/logs/rem-nightly.jsonl.
  *
  * Status today:
  *   - Steps 1, 2 shipped in slice-1 PR-1 (#414).
@@ -23,7 +29,14 @@
  *   - Step 5 (distillation) ships in this PR: calls `/ReflectMemories` with
  *     `execute: true` after maintenance succeeds. `dryRun` skips the call
  *     entirely (staging rows + spending model tokens are side effects).
- *   - Step 6 shipped in slice-1 PR-1.
+ *   - Step 6 (dedup-cluster stat, flair-quality Slice 1c): calls
+ *     `/MemoryDedupStats` after distillation. `dryRun` skips it (persisting
+ *     the stat file is a side effect); failure (e.g. the caller isn't admin
+ *     — the resource is admin-gated) is recorded in `errors` and does not
+ *     fail the cycle. See resources/MemoryDedupStats.ts for the server-side
+ *     computation and resources/dedup-cluster.ts for the stat's canonical
+ *     storage location (NOT this log — see those files' module docs for why).
+ *   - Step 7 shipped in slice-1 PR-1 (was step 6 before this PR).
  *
  * The audit row's `slice` field tells readers which steps populated which
  * counts: `slice: "1"` rows have `archived`/`expired` undefined; `slice:
@@ -268,7 +281,50 @@ export async function runNightlyCycle(opts) {
             errors.push(`distillation: ${describeApiError(err?.message ?? err)}`);
         }
     }
-    // Step 6: log
+    // Step 6 (flair-quality Slice 1c): instance-wide dedup-cluster stat.
+    // Distinct from every step above — NOT scoped to opts.agentId. Runs ONCE
+    // per cycle, after the per-agent passes (spec: "a new instance-wide step
+    // in the REM nightly runner... runs once per cycle, after the per-agent
+    // passes"). Skipped in dry-run for the same reason distillation is:
+    // persisting the stat file is a side effect. Non-fatal on failure — e.g.
+    // POST /MemoryDedupStats is admin-gated (resources/MemoryDedupStats.ts),
+    // so a non-admin agent's nightly cycle records a `dedup:` error here and
+    // otherwise completes normally; maintenance + distillation already stand.
+    //
+    // NOTE (flagged for review): if MULTIPLE agents on the same instance each
+    // run their own nightly cycle, each cycle triggers this same instance-wide
+    // sweep independently — the stat is recomputed N times a night rather than
+    // once. No cross-process guard was added (kept the smallest surface); the
+    // recomputation is idempotent (same inputs → same aggregate, just wasted
+    // work), not incorrect.
+    let dedup;
+    if (!opts.dryRun) {
+        try {
+            const dedupRaw = await opts.apiCall("POST", "/MemoryDedupStats", {});
+            const obj = (dedupRaw && typeof dedupRaw === "object") ? dedupRaw : {};
+            if (obj.error) {
+                errors.push(`dedup: ${describeApiError(obj.error)}`);
+            }
+            else if (typeof obj.clusterCount === "number" &&
+                typeof obj.largestClusterSize === "number" &&
+                typeof obj.totalMemoriesInClusters === "number" &&
+                typeof obj.computedAt === "string") {
+                dedup = {
+                    clusterCount: obj.clusterCount,
+                    largestClusterSize: obj.largestClusterSize,
+                    totalMemoriesInClusters: obj.totalMemoriesInClusters,
+                    computedAt: obj.computedAt,
+                };
+            }
+            else {
+                errors.push("dedup: unexpected /MemoryDedupStats response shape");
+            }
+        }
+        catch (err) {
+            errors.push(`dedup: ${describeApiError(err?.message ?? err)}`);
+        }
+    }
+    // Step 7: log
     const row = {
         ...baseRow,
         slice: sliceLabel,
@@ -281,6 +337,7 @@ export async function runNightlyCycle(opts) {
         archived,
         expired,
         candidates,
+        dedup,
         durationMs: Date.now() - startedMs,
         errors,
         // `consolidated` remains undefined — this runner has no consolidation

package/dist/resources/MemoryDedupStats.js

@@ -0,0 +1,161 @@
+/**
+ * MemoryDedupStats.ts — instance-wide near-duplicate CLUSTER count.
+ *
+ * POST /MemoryDedupStats — admin-only. Triggered once per REM nightly cycle
+ * (src/rem/runner.ts, after the per-agent maintenance/distillation passes —
+ * see that file's module doc for why this step is instance-wide rather than
+ * folded into the per-agent runner loop).
+ *
+ * flair-quality Slice 1c (ops/proposals/flair-quality-slice1c-dedup-spec.md).
+ * K&S split resolved to "Option C, server-side": Sherlock's hard security
+ * objection to a CLI-side computation was that embeddings are the most
+ * sensitive data in the system and must never leave the server; Kern's
+ * arch counter was that this doesn't fit REM's PER-AGENT pass (which also
+ * strips embeddings before handing memories to the model). Resolution:
+ * a SEPARATE server-side nightly job — this resource — that:
+ *   1. Reads embeddings DIRECTLY off `databases.flair.Memory` (same access
+ *      HealthDetail already has — resources/health.ts's `db.flair.Memory.
+ *      search({})` reads full records instance-wide for its own stats).
+ *   2. Uses them ONLY as HNSW query vectors, via `retrieveCandidates()`
+ *      (resources/semantic-retrieval-core.ts) called BARE — the same
+ *      in-process, no-HTTP pattern resources/MemoryBootstrap.ts already
+ *      uses to reuse SemanticSearch's retrieval core without going over the
+ *      wire. The embedding vector itself is never serialized into an HTTP
+ *      response or returned to a caller — it lives only in this process's
+ *      memory for the span of one ANN query, then is discarded.
+ *   3. Persists ONLY the aggregate `{ clusterCount, largestClusterSize,
+ *      totalMemoriesInClusters, computedAt }` to REM_DEDUP_STATS_PATH
+ *      (resources/dedup-cluster.ts) — never per-memory cluster membership
+ *      (Sherlock: that would itself be a disclosure surface), never on
+ *      Memory rows (would pollute the authority/attribution path — #735
+ *      zero-authority spine).
+ *
+ * Why the stat file lives on the SERVER's own filesystem (not written by
+ * the CLI-side runner, unlike the snapshot/audit-log artifacts in
+ * src/rem/snapshot.ts and src/rem/runner.ts): the runner's `apiCall` talks
+ * to `flairUrl`, which is not guaranteed to be the same host the CLI runs
+ * on (a remote/federated Flair is a real deployment shape — see
+ * src/rem/scheduler.ts's `FLAIR_URL` substitution). resources/health.ts's
+ * HealthDetail (Part 3 of this slice) is a Resource running INSIDE the same
+ * Harper process as this one, so writing here and reading there are
+ * guaranteed to be the same file regardless of where the triggering CLI
+ * lives. The runner's own audit-log row (src/rem/runner.ts) gets a COPY of
+ * the result for convenience/history, but this file is the canonical source
+ * `/HealthDetail` reads from.
+ *
+ * Auth: allowAdmin, matching the codebase's existing convention for
+ * INSTANCE-WIDE (not self-scoped) maintenance jobs — see MemoryReindex.ts
+ * (also admin-only, also a fleet-wide sweep) and
+ * test/unit/resource-allow.test.ts's structural ADMIN_ONLY list, which this
+ * resource is added to. Per-agent nightly steps (/MemoryMaintenance,
+ * /ReflectMemories) use allowVerified because they're scoped to the calling
+ * agent's own memories; this one is never scoped that way — it reads every
+ * agent's embeddings — so it follows the admin-gated precedent instead.
+ */
+import { Resource, databases } from "@harperfast/harper";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { allowAdmin } from "./agent-auth.js";
+import { retrieveCandidates } from "./semantic-retrieval-core.js";
+import { DEDUP_COSINE_THRESHOLD_DEFAULT } from "./dedup.js";
+import { countDedupClusters, DEDUP_CLUSTER_ANN_K_DEFAULT, DEDUP_CLUSTER_MAX_MEMORIES_DEFAULT, REM_DEDUP_STATS_PATH, } from "./dedup-cluster.js";
+const NOT_ARCHIVED = [{ attribute: "archived", comparator: "not_equal", value: true }];
+function persistStat(stat, pathOverride) {
+    const path = pathOverride ?? REM_DEDUP_STATS_PATH;
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(stat, null, 2) + "\n", { mode: 0o600 });
+}
+/**
+ * The DB-touching sweep, factored out of post() so it takes an explicit
+ * `ctx` and `nowOverride`/`pathOverride` rather than reaching for Resource
+ * internals — kept close to post() (not exported broadly) since it needs a
+ * live Harper `databases` handle and isn't unit-testable without one; the
+ * PURE part (countDedupClusters) is what's unit-tested, in
+ * dedup-cluster.ts's own test file.
+ */
+async function computeAndPersist(ctx, opts) {
+    const annK = opts?.annK ?? DEDUP_CLUSTER_ANN_K_DEFAULT;
+    const maxMemories = opts?.maxMemories ?? DEDUP_CLUSTER_MAX_MEMORIES_DEFAULT;
+    // ── 1. Load the sweep set: every non-archived memory's id + embedding,
+    // instance-wide (no agentId condition — near-duplicates ACROSS agents are
+    // exactly what this stat is for). Bounded to the most-recently-created
+    // maxMemories when the instance exceeds the safety cap (see
+    // dedup-cluster.ts's doc on why this is a defensive bound, not sampling).
+    const all = [];
+    for await (const record of databases.flair.Memory.search({
+        conditions: NOT_ARCHIVED,
+        select: ["id", "embedding", "createdAt"],
+    })) {
+        if (!record?.id || !Array.isArray(record.embedding) || record.embedding.length === 0)
+            continue;
+        all.push({ id: record.id, embedding: record.embedding, createdAt: record.createdAt });
+    }
+    let sweepSet = all;
+    if (all.length > maxMemories) {
+        sweepSet = [...all]
+            .sort((a, b) => (b.createdAt ?? "").localeCompare(a.createdAt ?? ""))
+            .slice(0, maxMemories);
+    }
+    // ── 2. Bounded-k ANN query per memory, via the SAME retrieval core
+    // SemanticSearch/MemoryBootstrap use, called bare (in-process, no HTTP —
+    // see module doc). Each memory's OWN embedding is the query vector; the
+    // vector never leaves this function (select: ["id"] — no embedding field
+    // comes back out, and nothing here is returned to an HTTP caller).
+    //
+    // limit: annK + 1 — a memory's own stored embedding is always its own
+    // closest match (cosine 1.0), so the unfiltered result set always
+    // contains the memory itself. Fetching one extra slot and filtering self
+    // out below (n.id === memory.id) keeps the REAL candidate-neighbor count
+    // at the documented annK, rather than silently examining annK-1.
+    const edges = [];
+    for (const memory of sweepSet) {
+        let neighbors;
+        try {
+            neighbors = await retrieveCandidates({
+                queryEmbedding: memory.embedding,
+                conditions: NOT_ARCHIVED,
+                limit: annK + 1,
+                hybrid: false,
+                scoring: "raw",
+                withSemSimilarity: true,
+                select: ["id"],
+                ctx,
+            });
+        }
+        catch {
+            // A single memory's ANN query failing (embedding engine hiccup, etc.)
+            // must not abort the whole sweep — skip it, the rest still counts.
+            continue;
+        }
+        for (const n of neighbors) {
+            if (!n?.id || n.id === memory.id)
+                continue;
+            const cosine = typeof n._semSimilarity === "number" ? n._semSimilarity : 0;
+            if (cosine >= DEDUP_COSINE_THRESHOLD_DEFAULT) {
+                edges.push({ a: memory.id, b: n.id });
+            }
+        }
+    }
+    // ── 3. Reduce edges → connected components (pure, unit-tested elsewhere).
+    const clusters = countDedupClusters(edges);
+    const computedAt = (opts?.nowOverride ?? new Date()).toISOString();
+    const result = { ...clusters, computedAt };
+    // ── 4. Persist server-side ONLY the aggregate (never per-memory edges).
+    persistStat(result, opts?.pathOverride);
+    return result;
+}
+export class MemoryDedupStats extends Resource {
+    async allowCreate() {
+        return allowAdmin(this.getContext?.());
+    }
+    async post(_data) {
+        const ctx = this.getContext?.();
+        try {
+            return await computeAndPersist(ctx);
+        }
+        catch (err) {
+            return new Response(JSON.stringify({ error: err?.message ?? String(err) }), { status: 500, headers: { "content-type": "application/json" } });
+        }
+    }
+}

package/dist/resources/dedup-cluster.js

@@ -0,0 +1,145 @@
+// ─── Instance-wide dedup-cluster counting primitives (Harper-free) ──────────
+// flair-quality Slice 1c (ops/proposals/flair-quality-slice1c-dedup-spec.md,
+// K&S-resolved to "Option C, server-side"). Same rationale as ./dedup.ts and
+// ./bm25.ts: the graph algorithm here is pure math over an edge list — no
+// Harper import, no embeddings, no DB — so it's unit-testable directly
+// against the SHIPPED clustering logic without a live Harper.
+//
+// ── THE INVARIANT ────────────────────────────────────────────────────────────
+// This module never sees embeddings and never sees memory content. It
+// consumes a list of {a, b} edges (memory-id pairs already determined to be
+// near-duplicates by the DB-touching sweep in resources/MemoryDedupStats.ts)
+// and reduces them to a small aggregate: how many CONNECTED COMPONENTS
+// (clusters) exist, how big the largest one is, and how many memories fall
+// into any cluster. Per Kern's design note (K&S round), a cluster of 5
+// memories is 1 cluster, not 10 pairwise edges — this module is what makes
+// that true (union-find over the edge list, not a raw edge count).
+//
+// No per-memory membership is retained past the union-find pass — the
+// public output is the aggregate ONLY (Sherlock's disclosure-surface
+// constraint: no per-memory cluster-membership data leaves this module).
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+/** Re-exported home for the single-source-of-truth cosine threshold this
+ *  module's caller (MemoryDedupStats.ts) gates edges on — see ./dedup.ts's
+ *  DEDUP_COSINE_THRESHOLD_DEFAULT (0.95). Not redefined here; this module
+ *  only counts edges, it never decides what counts as "near-duplicate". */
+export { DEDUP_COSINE_THRESHOLD_DEFAULT } from "./dedup.js";
+/** Bounded-k ANN fan-out per memory (Kern's efficiency framing: "bounded-k
+ *  ANN query per memory... O(n·k·log n)"). 10 is generous headroom for a
+ *  cosine>=0.95 near-duplicate gate — a true near-duplicate is overwhelmingly
+ *  likely to be its counterpart's #1 or #2 nearest neighbor, so even a large
+ *  (>10-member) cluster stays fully connected as long as each member finds
+ *  AT LEAST ONE clustermate within its own top-k (transitivity does the
+ *  rest via union-find). Exported so the sweep and its tests share one
+ *  tunable instead of a duplicated literal. */
+export const DEDUP_CLUSTER_ANN_K_DEFAULT = 10;
+/** Defensive cap on how many (non-archived) memories the nightly sweep will
+ *  walk in one cycle — protects wall-clock time on a very large instance.
+ *  This is a SAFETY bound, not a routine sampling strategy: real-world
+ *  self-hosted instances are expected to sit well under this for the
+ *  foreseeable future, and the brief explicitly asked to prefer the full ANN
+ *  sweep over sampling. When the instance exceeds this, the sweep covers the
+ *  most-recently-created N memories (deterministic, documented) rather than
+ *  a random sample. */
+export const DEDUP_CLUSTER_MAX_MEMORIES_DEFAULT = 20_000;
+/** Server-side stat artifact home (Slice 1c Part 2 — smallest-surface
+ *  storage choice). A single small JSON file under the SERVER's own
+ *  `~/.flair/`, written by MemoryDedupStats.ts's post() and read by
+ *  health.ts's HealthDetail — both run INSIDE the same Harper process, so
+ *  this is always the same file regardless of where the CLI/runner that
+ *  TRIGGERED the sweep is running (see MemoryDedupStats.ts's module doc for
+ *  why that distinction matters for remote/federated deployments). Mirrors
+ *  the `REM_PAUSE_FLAG` "small well-known file directly under ~/.flair/"
+ *  precedent in src/rem/runner.ts, rather than nesting under logs/ (this is
+ *  a single overwritten snapshot, not an append-only log). */
+export const REM_DEDUP_STATS_PATH = resolve(homedir(), ".flair", "rem-dedup-stats.json");
+/** Minimal union-find (disjoint-set) with path compression + union-by-rank.
+ *  Nodes are created lazily — a memory id only enters the structure when it
+ *  appears in at least one edge, so a memory with zero near-duplicate edges
+ *  (the common case) never shows up in the output at all. */
+class UnionFind {
+    parent = new Map();
+    rank = new Map();
+    ensure(x) {
+        if (!this.parent.has(x)) {
+            this.parent.set(x, x);
+            this.rank.set(x, 0);
+        }
+    }
+    find(x) {
+        this.ensure(x);
+        let root = x;
+        while (this.parent.get(root) !== root) {
+            root = this.parent.get(root);
+        }
+        // Path compression.
+        let cur = x;
+        while (this.parent.get(cur) !== root) {
+            const next = this.parent.get(cur);
+            this.parent.set(cur, root);
+            cur = next;
+        }
+        return root;
+    }
+    union(a, b) {
+        const ra = this.find(a);
+        const rb = this.find(b);
+        if (ra === rb)
+            return;
+        const rankA = this.rank.get(ra) ?? 0;
+        const rankB = this.rank.get(rb) ?? 0;
+        if (rankA < rankB) {
+            this.parent.set(ra, rb);
+        }
+        else if (rankA > rankB) {
+            this.parent.set(rb, ra);
+        }
+        else {
+            this.parent.set(rb, ra);
+            this.rank.set(ra, rankA + 1);
+        }
+    }
+    nodes() {
+        return [...this.parent.keys()];
+    }
+}
+/**
+ * Reduces a near-duplicate edge list to the cluster aggregate `flair
+ * quality` renders. A "cluster" requires >=2 connected memories — a memory
+ * with no qualifying edge never enters the graph, so it's correctly excluded
+ * (never counted as a size-1 "cluster").
+ *
+ * Self-loop edges (a === b — a memory paired with itself, which the sweep
+ * should already exclude, but this function stays defensive) are ignored:
+ * they can never form or grow a cluster.
+ *
+ * Duplicate/symmetric edges (the sweep may discover the SAME pair from both
+ * directions — A's neighbor search finds B, and independently B's finds A)
+ * are harmless: union() on an already-joined pair is a no-op.
+ */
+export function countDedupClusters(edges) {
+    const uf = new UnionFind();
+    for (const { a, b } of edges) {
+        if (a === b)
+            continue;
+        uf.union(a, b);
+    }
+    const sizeByRoot = new Map();
+    for (const id of uf.nodes()) {
+        const root = uf.find(id);
+        sizeByRoot.set(root, (sizeByRoot.get(root) ?? 0) + 1);
+    }
+    let clusterCount = 0;
+    let largestClusterSize = 0;
+    let totalMemoriesInClusters = 0;
+    for (const size of sizeByRoot.values()) {
+        if (size < 2)
+            continue; // shouldn't happen (a root only exists via an edge), but stay defensive
+        clusterCount++;
+        totalMemoriesInClusters += size;
+        if (size > largestClusterSize)
+            largestClusterSize = size;
+    }
+    return { clusterCount, largestClusterSize, totalMemoriesInClusters };
+}

package/dist/resources/health.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { getRerankStatus } from "./rerank-provider.js";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 import { getMigrationStatusSnapshot } from "./migrations/status.js";
+import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -206,7 +207,7 @@ export class HealthDetail extends Resource {
             for await (const a of db.flair.Agent.search({}))
                 agents.push(a);
             const blank = (id) => ({
-                id, memoryCount: 0, hashFallback: 0, writes24h: 0, lastWriteAt: null,
+                id, memoryCount: 0, hashFallback: 0, writes24h: 0, lastWriteAt: null, usageCount: 0,
             });
             const perAgentMap = new Map();
             for (const a of agents) {
@@ -219,6 +220,7 @@ export class HealthDetail extends Resource {
                     continue;
                 const row = perAgentMap.get(m.agentId) ?? blank(m.agentId);
                 row.memoryCount++;
+                row.usageCount += (m.usageCount ?? 0);
                 if (!m.embeddingModel || m.embeddingModel === "hash-512d")
                     row.hashFallback++;
                 if (m.createdAt) {
@@ -499,6 +501,36 @@ export class HealthDetail extends Resource {
         catch {
             stats.rem = null;
         }
+        // ── Dedup clusters (flair-quality Slice 1c) ──
+        // Cheap read: a single small stat file, not a recomputation. The
+        // computation itself is a nightly server-side sweep (POST
+        // /MemoryDedupStats, triggered once per REM nightly cycle — see
+        // src/rem/runner.ts + resources/MemoryDedupStats.ts's module doc) that
+        // NEVER runs inline with a GET /HealthDetail request. `null` covers both
+        // "REM hasn't computed it yet" (fresh instance) and "file unreadable" —
+        // `flair quality` renders either as an honest gap, never a false zero.
+        try {
+            const raw = await fsp.readFile(REM_DEDUP_STATS_PATH, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed &&
+                typeof parsed.clusterCount === "number" &&
+                typeof parsed.largestClusterSize === "number" &&
+                typeof parsed.totalMemoriesInClusters === "number" &&
+                typeof parsed.computedAt === "string") {
+                stats.dedup = {
+                    clusterCount: parsed.clusterCount,
+                    largestClusterSize: parsed.largestClusterSize,
+                    totalMemoriesInClusters: parsed.totalMemoriesInClusters,
+                    computedAt: parsed.computedAt,
+                };
+            }
+            else {
+                stats.dedup = null;
+            }
+        }
+        catch {
+            stats.dedup = null;
+        }
         // ── Migrations (flair#695: zero-touch boot-keyed auto-migration) ──
         // `{ id, rowsDone, rowsRemaining, state }` per registered migration, per
         // flair#695 §A. `cyclePhase: "pre-hash"` is the

package/dist/resources/mcp-oauth.js

@@ -19,7 +19,6 @@
  */
 import * as harper from "@harperfast/harper";
 import { mcpOAuthEnabled, mcpAuthConfig } from "./mcp-oauth-flag.js";
-import { mcpHandler } from "./mcp-handler.js";
 async function defaultLoadWithMCPAuth() {
     // Dynamic import so the dep is only required when the surface is enabled.
     const mod = (await import("@harperfast/oauth"));
@@ -49,6 +48,9 @@ export async function registerMcpOAuthRoute(deps = {}) {
         console.error("[mcp-oauth] @harperfast/oauth has no withMCPAuth export — /mcp NOT mounted.");
         return false;
     }
+    // Resolve the handler lazily (injected in tests; real module otherwise) — see
+    // the top-of-file note on why it isn't a static import.
+    const handler = deps.mcpHandler ?? (await import("./mcp-handler.js")).mcpHandler;
     // Read `server` lazily off the namespace (it's a runtime global on the Harper
     // module, not a static named export) so this module links cleanly even where a
     // stub build of @harperfast/harper lacks the export.
@@ -58,7 +60,7 @@ export async function registerMcpOAuthRoute(deps = {}) {
     // wrapper's iss/aud checks match the minted tokens even if this component
     // resolves a different node_modules copy of the plugin (docs/mcp-oauth.md
     // §"Using withMCPAuth from a different component").
-    srv.http(withMCPAuth(mcpHandler, {
+    srv.http(withMCPAuth(handler, {
         getConfig: () => mcpAuthConfig(),
     }), { urlPath: "/mcp" });
     console.error(`[mcp-oauth] /mcp mounted (OAuth-guarded); issuer=${config.issuer}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.25.4",
+  "version": "0.26.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",