@tpsdev-ai/flair 0.25.4 → 0.27.0

package/dist/doctor-client.js

@@ -373,6 +373,53 @@ export function planAgentIterations(keyAgentIds, agentFlag) {
         return [agentFlag];
     return [...keyAgentIds].sort();
 }
+// ── `doctor --fix` agent-id inference (flair#802b) ─────────────────────────
+//
+// `doctor` suggested `flair doctor --fix` to auto-wire an unconfigured MCP
+// client, but running that exact command failed — "no agent id known — pass
+// --agent <id>" — whenever the client had never been wired before (so there
+// was no existing block to read an agent id from) and neither --agent nor
+// FLAIR_AGENT_ID was set. The suggested fix didn't work as suggested. Two
+// pure decisions fix that without adding any new network/crypto surface:
+//
+//   1. inferSoleAgentId — when exactly one locally-keyed agent exists (the
+//      same keyAgentIds pool planAgentIterations already draws from, i.e.
+//      doctor's own "Keys found" enumeration), --fix can use it without
+//      being told: there's no other candidate it could mean. Two or more
+//      keys, or zero, are genuinely ambiguous/unanswerable and still require
+//      an explicit --agent (or registering one first) — this never guesses
+//      in either of those cases.
+//   2. fixCommandAgentHint — the *printed suggestion* (before --fix ever
+//      runs) splices in a concrete `--agent <id>` so the command a user
+//      copy-pastes actually works, using the first (sorted) known key id as
+//      the example. Only relevant when the id isn't already resolvable some
+//      other way (explicit --agent, FLAIR_AGENT_ID, or an id read off an
+//      already-wired client) — the caller checks that before calling this.
+/**
+ * The one case `doctor --fix` can safely infer an agent id without being
+ * told: exactly one locally-keyed agent. Zero keys (nothing to infer) or two
+ * or more (genuinely ambiguous — which one?) both return undefined; the
+ * caller must fall back to an explicit error telling the user what to do
+ * (register one, or pass --agent).
+ */
+export function inferSoleAgentId(keyAgentIds) {
+    return keyAgentIds.length === 1 ? keyAgentIds[0] : undefined;
+}
+/**
+ * Build the ` --agent <id>` fragment to splice into a suggested
+ * `flair doctor --fix ...` command so the printed suggestion is actually
+ * copy-pasteable rather than guaranteed to fail the moment nothing else
+ * (explicit --agent, FLAIR_AGENT_ID, an already-wired client's agent id) can
+ * supply one. Uses the first (sorted) known local key id as a concrete
+ * example. Returns "" when no agent id is known at all — the caller should
+ * tell the user to register one first rather than print a `--fix` suggestion
+ * that has nothing to work with either way.
+ */
+export function fixCommandAgentHint(keyAgentIds) {
+    if (keyAgentIds.length === 0)
+        return "";
+    return ` --agent ${[...keyAgentIds].sort()[0]}`;
+}
 /**
  * Render decision for one agent's registration-gate outcome, ahead of a
  * verified-read section (Fleet presence / Migrations). Returns null when the

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/docs/assets/flair-cross-orchestrator.cast

@@ -0,0 +1,33 @@
+{"version": 3, "term": {"cols": 96, "rows": 28}, "timestamp": 1778889600, "command": "/tmp/flair-cross-orchestrator-script.sh", "env": {"SHELL": "/bin/zsh"}}
+[0.245, "o", "\u001b[H\u001b[J"]
+[0.001, "o", "  Flair  \u00b7  same identity, every orchestrator\r\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n"]
+[1.3, "o", "$ # One agent identity. One memory store. Three orchestrators.\r\n"]
+[1.2, "o", "$ flair init --client all --agent flint\r\n"]
+[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude/mcp.json)\r\n"]
+[0.18, "o", "  \u001b[32m\u2713\u001b[0m Codex CLI     wired (~/.codex/config.toml)\r\n"]
+[0.18, "o", "  \u001b[32m\u2713\u001b[0m Gemini CLI    wired (~/.gemini/settings.json)\r\n\r\n"]
+[1.0, "o", "  Each MCP client now connects to:  http://127.0.0.1:9926\r\n"]
+[0.0, "o", "  Ed25519 keypair shared:           ~/.flair/keys/flint.ed25519\r\n\r\n"]
+[2.2, "o", "$ # \u2500\u2500 Claude Code: agent writes a memory \u2500\u2500\r\n"]
+[0.7, "o", "$ claude\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2mremember: we picked Postgres for replication-lag reasons; ScyllaDB ruled out by ops complexity\u001b[0m\r\n"]
+[1.8, "o", "  \u001b[32m\u2713\u001b[0m wrote memory mem_2026-05-14_3f9a (durability=persistent)\r\n\r\n"]
+[1.5, "o", "$ # \u2500\u2500 New session. Different orchestrator. Same identity. \u2500\u2500\r\n"]
+[1.0, "o", "$ codex\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2mwhat database did we pick and why?\u001b[0m\r\n"]
+[1.5, "o", "  \u001b[32m\u2713\u001b[0m bootstrap: 287 memories loaded for agent flint\r\n"]
+[0.4, "o", "  Postgres \u2014 chosen for replication-lag reasons.\r\n"]
+[0.0, "o", "  ScyllaDB was ruled out by ops complexity.\r\n"]
+[0.0, "o", "  \u001b[2m(source: mem_2026-05-14_3f9a, written via Claude Code 4m ago)\u001b[0m\r\n\r\n"]
+[2.0, "o", "$ # \u2500\u2500 New session. Another orchestrator. Same identity. \u2500\u2500\r\n"]
+[1.0, "o", "$ gemini\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2msummarize our recent infra decisions\u001b[0m\r\n"]
+[1.7, "o", "  \u001b[32m\u2713\u001b[0m bootstrap: same 287 memories, same soul, same Ed25519 identity\r\n"]
+[0.5, "o", "  \u2022 Postgres for replication-lag (2026-05-14)\r\n"]
+[0.0, "o", "  \u2022 Federation pair: local\u2192Fabric via Ed25519 (2026-05-05)\r\n"]
+[0.0, "o", "  \u2022 REM nightly cycle ships in v0.9.0 (2026-05-14)\r\n\r\n"]
+[2.5, "o", "  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n"]
+[0.0, "o", "  No SaaS in the middle.  No vendor lock.\r\n"]
+[0.0, "o", "  Memory follows the agent across orchestrators.\r\n"]
+[0.0, "o", "\r\n  github.com/tpsdev-ai/flair  \u00b7  Apache 2.0\r\n\r\n"]
+[5.0, "x", "0"]

package/docs/assets/flair-demo.cast

@@ -0,0 +1,18 @@
+{"version":3,"term":{"cols":80,"rows":24},"timestamp":1778359292,"command":"/tmp/flair-demo-script.sh","env":{"SHELL":"/bin/zsh"}}
+[0.245, "o", "\u001b[H\u001b[J"]
+[0.001, "o", "  Flair  ·  identity infrastructure for AI agents\r\n  ─────────────────────────────────────────────\r\n\r\n"]
+[1.520, "o", "$ # Agent writes a memory\r\n"]
+[0.628, "o", "$ flair memory add --agent flint-demo --content \"Postgres replication lag spiked when we added the read-replica\"\r\n"]
+[0.796, "o", "{\r\n  \"ok\": true\r\n}\r\n"]
+[1.411, "o", "\r\n"]
+[0.000, "o", "$ # Six months later — find it by meaning, not keywords\r\n"]
+[0.509, "o", "$ flair search \"why did our database fall behind during scaling\" --agent flint-demo\r\n"]
+[0.824, "o", "  Postgres replication lag spiked when we added the read-replica\r\n  (2026-05-09)\r\n"]
+[0.000, "o", "\r\n"]
+[2.054, "o", "\r\n$ # Same memory, every harness.\r\n"]
+[0.630, "o", "$ # Claude Code · Cursor · Codex CLI · Gemini CLI · Continue.dev · Goose\r\n$ #          all via   @tpsdev-ai/flair-mcp\r\n$ # LangGraph         @tpsdev-ai/langgraph-flair\r\n$ # OpenClaw          @tpsdev-ai/openclaw-flair\r\n$ # n8n               @tpsdev-ai/n8n-nodes-flair\r\n$ # Hermes Agent      packages/hermes-flair  (Python)\r\n$ # Pi agent          @tpsdev-ai/pi-flair\r\n"]
+[2.125, "o", "\r\n"]
+[0.000, "o", "  ─────────────────────────────────────────────\r\n"]
+[0.000, "o", "  Apache 2.0  ·  self-hosted  ·  no SaaS in the middle\r\n  github.com/tpsdev-ai/flair\r\n"]
+[0.000, "o", "\r\n"]
+[5.147, "x", "0"]