@tpsdev-ai/flair 0.8.0 → 0.8.2

package/README.md

@@ -4,23 +4,76 @@
 [![Docker Test](https://github.com/tpsdev-ai/flair/actions/workflows/docker-test.yml/badge.svg)](https://github.com/tpsdev-ai/flair/actions/workflows/docker-test.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Identity, memory, and soul for AI agents. Runs standalone or as part of a [TPS](https://tps.dev) office.**
+> **The memory system that gives agents a durable identity, not just durable facts. Federated. Crypto-isolated. Yours.**
 
-Agents forget everything between sessions. Flair gives them a persistent sense of self — who they are, what they know, how they think — backed by cryptographic identity and semantic search.
+Most agent memory systems store *facts*. Flair stores facts AND the agent's identity — its character, its values, its accumulated way of working. Same agent, different orchestrator: memory follows. Same network, different machine: memory federates. Same instance, different agents: memory is crypto-isolated end-to-end.
 
-Built on [Harper](https://harper.fast). Single process. No sidecars. Zero external API calls for embeddings.
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  same agent, same memory, every harness                          │
+│                                                                  │
+│  Claude Code  ─┐                                                 │
+│  Cursor       ─┤                                                 │
+│  Codex CLI    ─┼─[ flair-mcp ]─┐                                 │
+│  Gemini CLI   ─┤               │                                 │
+│  Continue.dev ─┤               │   ┌──────────────────────┐      │
+│  Goose        ─┘               ├─▶ │  Flair (rockit)      │      │
+│  LangGraph   ─[ langgraph-flair ]──│  Ed25519 / HNSW /    │      │
+│  OpenClaw    ─[ openclaw-flair  ]──│  Soul + Memory       │      │
+│  n8n         ─[ n8n-nodes-flair ]──└──────────┬───────────┘      │
+│  Hermes      ─[ hermes-flair    ]─┘           │ federation       │
+│  Pi agent    ─[ pi-flair        ]─┘           │ (hub/spoke)      │
+│                                               ▼                  │
+│                                    ┌──────────────────────┐      │
+│                                    │  Flair (Fabric hub)  │      │
+│                                    └──────────────────────┘      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+11 harness surfaces today. Pick whichever you're shipping in; the memory layer doesn't care. **[See the full integrations catalog →](docs/integrations.md)**
+
+## What it looks like
+
+![Flair: write a memory, find it by meaning, list of supported harnesses](docs/assets/flair-demo.gif)
+
+`flair memory add` writes a memory; `flair search` finds it by meaning, not keywords. The same memory is then visible to every harness in the catalog above.
+
+## How Flair compares
 
-## Why
+| | Flair | Mem0 | Honcho | Letta (MemGPT) | Built-ins (OAI/Anthropic/Google) |
+|---|---|---|---|---|---|
+| **License** | Apache 2.0 | Apache 2.0 | AGPL-3.0 | Apache 2.0 | proprietary |
+| **Self-host** | yes | yes (Docker) | yes (Docker) | yes | no |
+| **Managed cloud also offered** | no | yes (app.mem0.ai) | yes (app.honcho.dev) | no | only mode |
+| **Identity model** | **Ed25519 per agent (crypto-pinned)** | tenant-isolation | per-user soft tenant | runtime-bound | account-scoped |
+| **Federation (peer-to-peer)** | **yes — hub/spoke validated** | no | no | no | no |
+| **Cross-orchestrator** | **11+ harnesses, same memory** | several | several | runtime-bound | vendor-locked |
+| **Semantic search** | in-process (nomic-embed, no API calls) | yes | yes | yes | varies |
+| **Soul / persistent character** | **first-class** | optional | persona-shaped | optional | no |
+
+Mem0, Honcho, and Letta are all open-source and self-hostable — credit where it's due. That's why we don't lead with "open source" as the differentiator. The cells in **bold** are the ones that, in our reading, no other system can claim cleanly today: crypto-pinned per-agent identity, peer-to-peer federation, the breadth of cross-orchestrator integrations, and soul as a first-class primitive.
+
+The honest gaps:
+
+- Mem0's **cloud sync UX** is more polished if you're OK with their hosting.
+- Honcho's **persona model** is more developed if rich personality modeling is your priority.
+- Letta's **runtime integration** is tighter if you're building on their agent loop.
+
+If you need any of those specifically, use them. If you need crypto-pinned identity + federation + cross-orchestrator breadth + soul-as-a-feature — that's the gap Flair fills.
+
+## Why this exists
 
 Every agent framework gives you chat history. None of them give you *identity*.
 
 An agent that can't remember what it learned yesterday, can't prove who it is to another agent, and loses its personality on restart isn't really an agent. It's a stateless function with a system prompt.
 
-Flair fixes that:
+Flair fixes that with three primitives:
+
+- **Identity** — Ed25519 key pairs. Agents sign every request. No passwords, no API keys, no shared secrets. Cross-agent reads are refused at the server, not by client convention.
+- **Memory** — Persistent knowledge with semantic search (in-process [nomic-embed-text](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF), 768-dim, no API calls). Tiered durability (`permanent` / `persistent` / `standard` / `ephemeral`). Temporal validity. Decay-and-retrieval-aware composite scoring.
+- **Soul** — Personality, values, procedures. The stuff that makes an agent *that agent*. Re-injected every turn via the context-engine plugin so it doesn't drift across long sessions.
 
-- **Identity** — Ed25519 key pairs. Agents sign every request. No passwords, no API keys, no shared secrets.
-- **Memory** — Persistent knowledge with semantic search. Write a lesson learned today, find it six months from now by meaning, not keywords.
-- **Soul** — Personality, values, procedures. The stuff that makes an agent *that agent*, not just another LLM wrapper.
+Built on [Harper](https://harper.fast). Single process. No sidecars. Zero external API calls for embeddings. **[Supply-chain policy](docs/supply-chain-policy.md)** documents the bake-time + dep-pinning we run to keep this honest.
 
 ## How It Works
 

package/dist/bridges/builtins/chatgpt.js

@@ -0,0 +1,220 @@
+/**
+ * Built-in bridge: chatgpt
+ *
+ * Imports ChatGPT memories into Flair.
+ *
+ * Verified workflow (authoritative source — Anthropic's
+ * claude.com/import-memory page describing the ChatGPT→Claude migration,
+ * verified 2026-05-10): the canonical user path for moving ChatGPT
+ * memories is the text-paste workflow. Anthropic publishes the extraction
+ * prompt and frames the migration as copy-paste, not file-import:
+ *
+ *   1. Run this prompt in ChatGPT:
+ *        "Please share all the memories you have stored about me. List
+ *        each memory as a separate bullet point, using plain language."
+ *   2. Copy the resulting bulleted text block
+ *   3. Paste into a .txt or .md file
+ *   4. Run: flair bridge import chatgpt --source memories.txt --agent <id>
+ *
+ * Less-certain (OpenAI's data-export help article was not directly
+ * fetchable during verification; third-party guides disagree on whether
+ * ChatGPT memories appear in the OpenAI data-export ZIP at all). The
+ * bridge does NOT auto-discover anything inside a directory source for
+ * this reason — no Anthropic-published source identifies a known memories
+ * filename inside the ChatGPT export, and silently picking up a wrong
+ * file would be worse than asking the user to point at the file
+ * explicitly. Directory inputs throw with workflow guidance pointing
+ * back at the extraction prompt.
+ *
+ * Primary input: plain text file. One memory per line, optionally bullet-
+ * prefixed (-, *, •, 1., 1)). Empty lines are skipped.
+ *
+ * Fallback input: JSON file containing { memories: [...] } or a top-level
+ * array. Supports third-party tools that scrape memory UI into JSON.
+ *
+ * Round-trip: one-way. ChatGPT's memory store is closed.
+ *
+ * Usage:
+ *   flair bridge import chatgpt --source memories.txt --agent <id>
+ *   flair bridge import chatgpt --source memories.json --agent <id>  (third-party JSON)
+ */
+import { promises as fsp } from "node:fs";
+import { BridgeRuntimeError } from "../types.js";
+// Strip common bullet/numbered-list prefixes from a line.
+// Examples: "- foo" → "foo"; "* foo" → "foo"; "• foo" → "foo";
+//   "1. foo" → "foo"; "1) foo" → "foo"; "  - foo" → "foo".
+function stripBulletPrefix(line) {
+    const trimmed = line.trim();
+    // Markdown bullets + unicode bullet
+    const bulletMatch = trimmed.match(/^([-*•])\s+(.*)$/);
+    if (bulletMatch)
+        return bulletMatch[2];
+    // Numbered list: "1. ", "1) ", "12. ", etc.
+    const numberedMatch = trimmed.match(/^\d+[.)]\s+(.*)$/);
+    if (numberedMatch)
+        return numberedMatch[1];
+    return trimmed;
+}
+function parsePlainText(raw) {
+    return raw
+        .split(/\r?\n/)
+        .map(stripBulletPrefix)
+        .filter((line) => line.length > 0);
+}
+async function* importChatGPT(opts, ctx) {
+    const { isAbsolute, resolve } = await import("node:path");
+    const sourceArg = typeof opts.source === "string" ? opts.source : "";
+    if (!sourceArg) {
+        throw new BridgeRuntimeError({
+            bridge: "chatgpt",
+            op: "import",
+            path: "(unset)",
+            field: "source",
+            expected: "path to a .txt/.md/.json file containing your ChatGPT memories",
+            got: "missing",
+            hint: "pass --source <path>; example: flair bridge import chatgpt --source memories.txt --agent <id>",
+        });
+    }
+    const filePath = isAbsolute(sourceArg) ? sourceArg : resolve(process.cwd(), sourceArg);
+    // Stat first — directory inputs are not supported for chatgpt because
+    // OpenAI's data export contains no memories file. Surface that explicitly
+    // rather than silently failing on a missing memory.json.
+    let isDir = false;
+    try {
+        const stat = await fsp.stat(filePath);
+        isDir = stat.isDirectory();
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge: "chatgpt",
+            op: "import",
+            path: filePath,
+            field: "source",
+            expected: "readable .txt/.md/.json file",
+            got: err?.code ?? "ENOENT",
+            hint: `could not resolve source: ${err?.message ?? err}`,
+        });
+    }
+    if (isDir) {
+        throw new BridgeRuntimeError({
+            bridge: "chatgpt",
+            op: "import",
+            path: filePath,
+            field: "source",
+            expected: "a file (not a directory)",
+            got: "directory",
+            hint: "Point --source at a specific file, not a directory. The canonical workflow (per Anthropic's published ChatGPT→Claude migration guide) is the text-paste path: run the extraction prompt in ChatGPT (\"List all memories you have about me as bullet points\"), paste the result into a .txt file, and pass that file as --source.",
+        });
+    }
+    ctx.log.info("reading ChatGPT memory dump", { path: filePath });
+    let raw;
+    try {
+        raw = await fsp.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge: "chatgpt",
+            op: "import",
+            path: filePath,
+            field: "source.path",
+            expected: "readable file",
+            got: err?.code ?? "ENOENT",
+            hint: `could not read source file: ${err?.message ?? err}`,
+        });
+    }
+    // Detect input shape. Try JSON parse first; if it fails AND the file
+    // doesn't have a .json extension, fall back to plain-text line parse.
+    // This makes JSON the sticky path for users who clearly meant JSON
+    // (so we don't silently treat broken JSON as 1-line "memories"), and
+    // text the natural path for the migration-prompt workflow.
+    const isJsonExt = /\.(json)$/i.test(filePath);
+    let memories = [];
+    let parsed = null;
+    let jsonParseErr = null;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        jsonParseErr = err;
+    }
+    if (parsed !== null) {
+        // Parsed as JSON — accept { memories: [...] } or top-level array.
+        if (Array.isArray(parsed)) {
+            memories = parsed;
+        }
+        else if (Array.isArray(parsed?.memories)) {
+            memories = parsed.memories;
+        }
+        else if (Array.isArray(parsed?.user_memory)) {
+            memories = parsed.user_memory; // older third-party shape
+        }
+        else {
+            throw new BridgeRuntimeError({
+                bridge: "chatgpt",
+                op: "import",
+                path: filePath,
+                field: "(document)",
+                expected: "{ memories: [...] } or top-level array",
+                got: typeof parsed,
+                hint: `JSON parsed but shape is unexpected — keys at root: ${Object.keys(parsed ?? {}).join(", ") || "none"}. If you meant to pass a plain-text bullet list, save it as .txt instead of .json.`,
+            });
+        }
+    }
+    else if (isJsonExt) {
+        // Extension says JSON but parse failed — surface that, don't silently fall back.
+        throw new BridgeRuntimeError({
+            bridge: "chatgpt",
+            op: "import",
+            path: filePath,
+            field: "(document)",
+            expected: "valid JSON (file has .json extension)",
+            got: "parse error",
+            hint: `JSON parse failed: ${jsonParseErr?.message ?? jsonParseErr}. If you meant plain text, rename to .txt.`,
+        });
+    }
+    else {
+        // Plain-text path.
+        memories = parsePlainText(raw);
+    }
+    ctx.log.info("found memories", { count: memories.length });
+    let kept = 0;
+    let skipped = 0;
+    for (let i = 0; i < memories.length; i++) {
+        const m = memories[i];
+        // Lenient extract — try several common shapes.
+        const content = typeof m === "string" ? m
+            : typeof m?.content === "string" ? m.content
+                : typeof m?.text === "string" ? m.text
+                    : typeof m?.body === "string" ? m.body
+                        : null;
+        if (!content || content.trim() === "") {
+            skipped++;
+            continue;
+        }
+        kept++;
+        const objM = typeof m === "object" && m !== null ? m : null;
+        yield {
+            foreignId: typeof objM?.id === "string" ? `chatgpt:${objM.id}` : `chatgpt:idx-${i}`,
+            content: content.trim(),
+            createdAt: typeof objM?.created_at === "string" ? objM.created_at : undefined,
+            tags: ["source:chatgpt", "import:chatgpt"],
+            durability: "persistent",
+        };
+    }
+    ctx.log.info("import complete", { kept, skipped });
+}
+export const chatgptMemoryBridge = {
+    name: "chatgpt",
+    version: 1,
+    kind: "file",
+    description: "Import ChatGPT memories (paste-the-prompt-output workflow) into Flair",
+    options: {
+        source: {
+            description: "Path to a .txt/.md file with one memory per line/bullet, OR a .json file with { memories: [...] }.",
+            required: true,
+        },
+    },
+    import: importChatGPT,
+    // No export — ChatGPT's memory store is closed; round-trip would have
+    // nowhere useful to write back to.
+};

package/dist/bridges/builtins/claude-project.js

@@ -0,0 +1,275 @@
+/**
+ * Built-in bridge: claude-project
+ *
+ * Imports Claude memories into Flair.
+ *
+ * Verified workflow (authoritative source — claude.com/import-memory,
+ * verified 2026-05-10): Anthropic's published memory-import flow is
+ * copy-paste only. The user runs an extraction prompt in Claude, copies
+ * the result, and pastes it into Claude's memory settings (or, in our
+ * case, into a local file we then import).
+ *
+ * Less-certain (third-party sources disagree, Anthropic's data-export
+ * help article does not publish the file list): whether the standard
+ * Claude data-export ZIP (Settings → Privacy → Export data) contains a
+ * `memories.json` file. The bridge hedges by accepting either path:
+ *   - Primary: the copy-paste workflow → user-staged .txt/.md/.json
+ *   - Fallback: an extracted data-export directory whose memories file
+ *     is named `memories.json` (auto-discovered alongside the user-staged
+ *     names — see `findMemoryFileInDir` below)
+ *
+ * Primary input: plain text (.txt or .md) — bullet-prefixed or raw lines.
+ * Fallback input: JSON containing `{ memories: [...] }` or top-level array.
+ * Optional: a `project.json` file alongside supplying `{ name: "..." }`
+ * to label the imported memories with a project subject + foreignId.
+ *
+ * Round-trip: one-way. Claude's memory store is closed.
+ *
+ * Usage:
+ *   flair bridge import claude-project --source memory.txt --agent <id>
+ *   flair bridge import claude-project --source memory.json --agent <id>
+ *   flair bridge import claude-project --source ./claude-export --agent <id>
+ *     (where ./claude-export contains memory.{txt,md,json} or memories.json,
+ *      plus optional project.json)
+ */
+import { promises as fsp } from "node:fs";
+import { join, dirname } from "node:path";
+import { BridgeRuntimeError } from "../types.js";
+function stripBulletPrefix(line) {
+    const trimmed = line.trim();
+    const bulletMatch = trimmed.match(/^([-*•])\s+(.*)$/);
+    if (bulletMatch)
+        return bulletMatch[2];
+    const numberedMatch = trimmed.match(/^\d+[.)]\s+(.*)$/);
+    if (numberedMatch)
+        return numberedMatch[1];
+    return trimmed;
+}
+function parsePlainText(raw) {
+    return raw
+        .split(/\r?\n/)
+        .map(stripBulletPrefix)
+        .filter((line) => line.length > 0);
+}
+// Best-effort discovery of the "memory file" inside a directory source.
+// Order:
+//   1. memory.txt    — user-staged from the copy-paste workflow (most common)
+//   2. memory.md     — user-staged markdown variant
+//   3. memory.json   — user-staged JSON wrapper
+//   4. memories.json — possible filename inside an Anthropic data-export
+//                      ZIP. Anthropic's data-export help article doesn't
+//                      publish the ZIP file list and third-party tools
+//                      disagree on whether this file is present; including
+//                      it here is a cheap hedge so the bridge handles either
+//                      reality without a follow-up patch.
+// Returns the first that exists, or null if none are present.
+async function findMemoryFileInDir(dir) {
+    for (const name of ["memory.txt", "memory.md", "memory.json", "memories.json"]) {
+        const candidate = join(dir, name);
+        try {
+            const stat = await fsp.stat(candidate);
+            if (stat.isFile())
+                return candidate;
+        }
+        catch {
+            // not present, continue
+        }
+    }
+    return null;
+}
+async function* importClaudeProject(opts, ctx) {
+    const { isAbsolute, resolve } = await import("node:path");
+    const sourceArg = typeof opts.source === "string" ? opts.source : "";
+    if (!sourceArg) {
+        throw new BridgeRuntimeError({
+            bridge: "claude-project",
+            op: "import",
+            path: "(unset)",
+            field: "source",
+            expected: "path to a .txt/.md/.json file (or directory containing one)",
+            got: "missing",
+            hint: "pass --source <path>; example: flair bridge import claude-project --source memory.txt --agent <id>",
+        });
+    }
+    const sourceAbs = isAbsolute(sourceArg) ? sourceArg : resolve(process.cwd(), sourceArg);
+    let filePath;
+    let sourceDir;
+    try {
+        const stat = await fsp.stat(sourceAbs);
+        if (stat.isDirectory()) {
+            sourceDir = sourceAbs;
+            const found = await findMemoryFileInDir(sourceAbs);
+            if (!found) {
+                throw new BridgeRuntimeError({
+                    bridge: "claude-project",
+                    op: "import",
+                    path: sourceAbs,
+                    field: "source",
+                    expected: "directory containing memory.txt, memory.md, or memory.json",
+                    got: "directory with no memory file",
+                    hint: "Claude's memory export is UI-only — copy your memory from Settings → Capabilities into memory.txt inside this directory, or pass the file path directly as --source.",
+                });
+            }
+            filePath = found;
+        }
+        else {
+            sourceDir = dirname(sourceAbs);
+            filePath = sourceAbs;
+        }
+    }
+    catch (err) {
+        if (err instanceof BridgeRuntimeError)
+            throw err;
+        throw new BridgeRuntimeError({
+            bridge: "claude-project",
+            op: "import",
+            path: sourceAbs,
+            field: "source",
+            expected: "readable file or directory",
+            got: err?.code ?? "ENOENT",
+            hint: `could not resolve source: ${err?.message ?? err}`,
+        });
+    }
+    if (filePath.endsWith(".zip")) {
+        throw new BridgeRuntimeError({
+            bridge: "claude-project",
+            op: "import",
+            path: filePath,
+            field: "source",
+            expected: "extracted file or directory",
+            got: "zip archive",
+            hint: `extract the .zip first, then point --source at the extracted directory or file:\n  unzip ${filePath} -d ./claude-export && flair bridge import claude-project --source ./claude-export --agent <id>`,
+        });
+    }
+    ctx.log.info("reading Claude memory dump", { path: filePath });
+    let raw;
+    try {
+        raw = await fsp.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge: "claude-project",
+            op: "import",
+            path: filePath,
+            field: "source.path",
+            expected: "readable file",
+            got: err?.code ?? "ENOENT",
+            hint: `could not read source file: ${err?.message ?? err}`,
+        });
+    }
+    // Detect input shape. JSON path is sticky for .json extension; text path
+    // for .txt/.md. For files without a recognized extension, try JSON first
+    // and fall back to text on parse failure.
+    const isJsonExt = /\.(json)$/i.test(filePath);
+    let memories = [];
+    let parsed = null;
+    let jsonParseErr = null;
+    if (isJsonExt) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            jsonParseErr = err;
+        }
+    }
+    else {
+        // For non-.json extensions, attempt JSON only as a fallback in case
+        // the user named a JSON file with a wrong extension. Otherwise treat
+        // as plain text.
+        try {
+            const candidate = JSON.parse(raw);
+            if (Array.isArray(candidate) || (candidate && typeof candidate === "object" && (Array.isArray(candidate.memories) || Array.isArray(candidate.user_memory)))) {
+                parsed = candidate;
+            }
+        }
+        catch {
+            // not JSON — fall through to plain-text path
+        }
+    }
+    if (parsed !== null) {
+        if (Array.isArray(parsed)) {
+            memories = parsed;
+        }
+        else if (Array.isArray(parsed?.memories)) {
+            memories = parsed.memories;
+        }
+        else {
+            throw new BridgeRuntimeError({
+                bridge: "claude-project",
+                op: "import",
+                path: filePath,
+                field: "(document)",
+                expected: "{ memories: [...] } or top-level array",
+                got: typeof parsed,
+                hint: `JSON parsed but shape is unexpected — keys at root: ${Object.keys(parsed ?? {}).join(", ") || "none"}. If you meant plain text, save as .txt instead of .json.`,
+            });
+        }
+    }
+    else if (isJsonExt) {
+        throw new BridgeRuntimeError({
+            bridge: "claude-project",
+            op: "import",
+            path: filePath,
+            field: "(document)",
+            expected: "valid JSON (file has .json extension)",
+            got: "parse error",
+            hint: `JSON parse failed: ${jsonParseErr?.message ?? jsonParseErr}. If you meant plain text, rename to .txt.`,
+        });
+    }
+    else {
+        // Plain-text path.
+        memories = parsePlainText(raw);
+    }
+    ctx.log.info("found memories", { count: memories.length });
+    // Load project.json (optional) to derive subject and project name for foreignId.
+    let projectName = "unknown";
+    try {
+        const projectRaw = await fsp.readFile(join(sourceDir, "project.json"), "utf-8");
+        const project = JSON.parse(projectRaw);
+        projectName = project.name || "unknown";
+    }
+    catch {
+        ctx.log.debug("no project.json found, using default project name", { dir: sourceDir });
+    }
+    const subject = projectName !== "unknown" ? projectName : undefined;
+    let kept = 0;
+    let skipped = 0;
+    for (let i = 0; i < memories.length; i++) {
+        const m = memories[i];
+        const content = typeof m === "string" ? m
+            : typeof m?.content === "string" ? m.content
+                : typeof m?.text === "string" ? m.text
+                    : null;
+        if (!content || content.trim() === "") {
+            skipped++;
+            continue;
+        }
+        kept++;
+        const objM = typeof m === "object" && m !== null ? m : null;
+        yield {
+            foreignId: typeof objM?.id === "string"
+                ? `claude-project:${projectName}:${objM.id}`
+                : `claude-project:${projectName}:idx-${i}`,
+            content: content.trim(),
+            subject,
+            createdAt: typeof objM?.created_at === "string" ? objM.created_at : undefined,
+            tags: ["source:claude-project", "import:claude-project"],
+            durability: "persistent",
+        };
+    }
+    ctx.log.info("import complete", { kept, skipped, project: projectName });
+}
+export const claudeProjectMemoryBridge = {
+    name: "claude-project",
+    version: 1,
+    kind: "file",
+    description: "Import Claude memory (Settings → Capabilities copy-paste workflow) into Flair",
+    options: {
+        source: {
+            description: "Path to a .txt/.md file with one memory per line/bullet, OR a .json file with { memories: [...] }, OR a directory containing memory.{txt,md,json} (and optional project.json).",
+            required: true,
+        },
+    },
+    import: importClaudeProject,
+    // No export — Claude's memory store is closed.
+};

package/dist/bridges/builtins/index.js

@@ -13,7 +13,10 @@
  *   Then register it here. See specs/FLAIR-BRIDGES.md §2 for shapes A/B.
  */
 import { agenticStackDescriptor } from "./agentic-stack.js";
+import { claudeProjectMemoryBridge } from "./claude-project.js";
+import { chatgptMemoryBridge } from "./chatgpt.js";
 import { markdownMemoryBridge } from "./markdown.js";
+import { mem0MemoryBridge } from "./mem0.js";
 function builtinDescriptor(d) {
     return {
         discovered: {
@@ -43,7 +46,10 @@ function builtinPlugin(p) {
 /** All bridges shipped inside @tpsdev-ai/flair. Order doesn't matter. */
 export const BUILTINS = [
     builtinDescriptor(agenticStackDescriptor),
+    builtinPlugin(claudeProjectMemoryBridge),
+    builtinPlugin(chatgptMemoryBridge),
     builtinPlugin(markdownMemoryBridge),
+    builtinPlugin(mem0MemoryBridge),
 ];
 /** Map name → descriptor/plugin for O(1) runtime lookup. */
 export const BUILTIN_BY_NAME = new Map(BUILTINS.map((b) => [b.discovered.name, b]));

package/dist/bridges/builtins/mem0.js

@@ -0,0 +1,247 @@
+/**
+ * Built-in bridge: mem0
+ *
+ * Imports memories from a Mem0 instance (cloud at api.mem0.ai or self-hosted)
+ * into Flair. Pulls every memory for a given user_id via the Mem0 v1 GET
+ * /v1/memories/ endpoint, paginating with page/page_size until exhausted.
+ * Each imported row becomes one Flair memory tagged `source:mem0` +
+ * `import:mem0`, durability `persistent`.
+ *
+ * One-way import (we don't sync back). This backs the "switch off SaaS
+ * memory in 30 seconds" positioning.
+ *
+ * API schema (verified against api.mem0.ai/openapi.json on 2026-05-10):
+ *   GET /v1/memories/?user_id=<id>&page=<n>&page_size=<n>
+ *   Authorization: Token <api-key>
+ *
+ *   Response shape A (v1, bare array — self-hosted + cloud v1):
+ *     [ { id, memory, created_at, ... }, ... ]
+ *     Pagination ends when an empty array is returned.
+ *
+ *   Response shape B (v3 / DRF-style paginated envelope):
+ *     { count, next, previous, results: [...] }
+ *     Pagination ends when `next` is null.
+ *
+ *   The bridge auto-detects which shape the server returns and handles both.
+ *
+ * Why a Shape B (code) bridge and not Shape A (YAML descriptor):
+ *   - The Mem0 API requires bearer-auth headers and pagination.
+ *   - The Shape A file-based parser can't drive a REST API.
+ *   - Error handling needs to distinguish 401/403/404 from network failures
+ *     from malformed responses — easier to express in TS.
+ *
+ * Usage:
+ *   flair bridge import mem0 --user <id> --api-key <key> --agent <flair-id>
+ *   flair bridge import mem0 --user <id> --base-url https://mem0.example.com --agent <flair-id>
+ *   MEM0_API_KEY=<key> flair bridge import mem0 --user <id> --agent <flair-id>
+ */
+import { BridgeRuntimeError } from "../types.js";
+function isPaginatedEnvelope(body) {
+    return !Array.isArray(body) && typeof body === "object" && body !== null && Array.isArray(body.results);
+}
+async function* importMem0(opts, ctx) {
+    const userId = typeof opts.user === "string" ? opts.user : "";
+    if (!userId) {
+        throw new BridgeRuntimeError({
+            bridge: "mem0",
+            op: "import",
+            field: "user",
+            expected: "Mem0 user_id string",
+            got: "missing",
+            hint: "pass --user <id>; example: flair bridge import mem0 --user <id> --api-key <key> --agent <flair-id>",
+        });
+    }
+    const apiKey = typeof opts.apiKey === "string" ? opts.apiKey : "";
+    if (!apiKey) {
+        throw new BridgeRuntimeError({
+            bridge: "mem0",
+            op: "import",
+            field: "apiKey",
+            expected: "Mem0 API token (cloud or self-hosted)",
+            got: "missing",
+            hint: "pass --api-key <token> or set MEM0_API_KEY in the environment",
+        });
+    }
+    const baseUrl = typeof opts.baseUrl === "string" && opts.baseUrl.length > 0
+        ? opts.baseUrl.replace(/\/+$/, "")
+        : "https://api.mem0.ai";
+    const maxPages = typeof opts.maxPages === "number" ? opts.maxPages : 0;
+    const pageSize = 100;
+    ctx.log.info("starting mem0 import", {
+        user_id: userId,
+        base_url: baseUrl,
+    });
+    let pageCount = 0;
+    let totalKept = 0;
+    let pageNum = 1;
+    let cursor = `${baseUrl}/v1/memories/?user_id=${encodeURIComponent(userId)}&page=${pageNum}&page_size=${pageSize}`;
+    while (cursor !== null) {
+        if (maxPages > 0 && pageCount >= maxPages) {
+            ctx.log.info("stopping at max-pages limit", { pages: pageCount, kept: totalKept });
+            break;
+        }
+        ctx.log.debug("fetching page", { url: cursor, page: pageCount + 1 });
+        let res;
+        try {
+            res = await ctx.fetch(cursor, {
+                headers: {
+                    Authorization: `Token ${apiKey}`,
+                    Accept: "application/json",
+                },
+            });
+        }
+        catch (err) {
+            throw new BridgeRuntimeError({
+                bridge: "mem0",
+                op: "import",
+                path: cursor,
+                field: "fetch",
+                expected: "HTTP 200",
+                got: `network error: ${err?.message ?? err}`,
+                hint: "check the base URL is reachable and the network is up",
+            });
+        }
+        if (res.status === 401) {
+            throw new BridgeRuntimeError({
+                bridge: "mem0",
+                op: "import",
+                path: cursor,
+                field: "apiKey",
+                expected: "valid Mem0 API token",
+                got: "HTTP 401 Unauthorized",
+                hint: "the API key was rejected — check it's valid and scoped to the user_id",
+            });
+        }
+        if (res.status === 403) {
+            throw new BridgeRuntimeError({
+                bridge: "mem0",
+                op: "import",
+                path: cursor,
+                field: "apiKey",
+                expected: "authorized token",
+                got: "HTTP 403 Forbidden",
+                hint: "the API key doesn't have permission to read memories for this user_id",
+            });
+        }
+        if (res.status === 404) {
+            throw new BridgeRuntimeError({
+                bridge: "mem0",
+                op: "import",
+                path: cursor,
+                field: "user",
+                expected: "existing user_id",
+                got: "HTTP 404 Not Found",
+                hint: `user_id "${userId}" was not found on this Mem0 instance`,
+            });
+        }
+        if (!res.ok) {
+            const body = await res.text().catch(() => "(could not read body)");
+            throw new BridgeRuntimeError({
+                bridge: "mem0",
+                op: "import",
+                path: cursor,
+                field: "response",
+                expected: "HTTP 200",
+                got: `HTTP ${res.status} ${res.statusText}`,
+                hint: `unexpected response (${res.status}): ${body.slice(0, 200)}`,
+            });
+        }
+        let body;
+        try {
+            const text = await res.text();
+            if (text.trim() === "") {
+                throw new BridgeRuntimeError({
+                    bridge: "mem0",
+                    op: "import",
+                    path: cursor,
+                    field: "(response)",
+                    expected: "JSON body",
+                    got: "empty response",
+                    hint: "the Mem0 API returned an empty body — check the instance is healthy",
+                });
+            }
+            body = JSON.parse(text);
+        }
+        catch (err) {
+            if (err instanceof BridgeRuntimeError)
+                throw err;
+            throw new BridgeRuntimeError({
+                bridge: "mem0",
+                op: "import",
+                path: cursor,
+                field: "(response)",
+                expected: "valid JSON: bare array OR { results: [...], next: string|null }",
+                got: "parse error",
+                hint: `could not parse response: ${err?.message ?? err}`,
+            });
+        }
+        let mems;
+        let nextCursor;
+        if (Array.isArray(body)) {
+            // v1 bare-array shape — page until we get an empty array.
+            mems = body;
+            nextCursor = mems.length === 0 || mems.length < pageSize
+                ? null
+                : `${baseUrl}/v1/memories/?user_id=${encodeURIComponent(userId)}&page=${pageNum + 1}&page_size=${pageSize}`;
+            pageNum++;
+        }
+        else if (isPaginatedEnvelope(body)) {
+            // v3 / DRF-style envelope — use server-provided next URL.
+            mems = body.results;
+            nextCursor = typeof body.next === "string" && body.next.length > 0 ? body.next : null;
+        }
+        else {
+            throw new BridgeRuntimeError({
+                bridge: "mem0",
+                op: "import",
+                path: cursor,
+                field: "(response)",
+                expected: "bare array OR { results: [...], next: string|null }",
+                got: typeof body,
+                hint: `unexpected response shape — got ${typeof body}, expected an array or paginated envelope`,
+            });
+        }
+        ctx.log.debug("received page", { count: mems.length, next: nextCursor });
+        for (const m of mems) {
+            const content = typeof m?.memory === "string" ? m.memory : "";
+            if (!content || content.trim() === "")
+                continue;
+            totalKept++;
+            yield {
+                foreignId: `mem0:${m.id}`,
+                content,
+                createdAt: typeof m?.created_at === "string" ? m.created_at : undefined,
+                tags: ["source:mem0", "import:mem0"],
+                durability: "persistent",
+            };
+        }
+        pageCount++;
+        cursor = nextCursor;
+    }
+    ctx.log.info("mem0 import complete", { pages: pageCount, kept: totalKept });
+}
+export const mem0MemoryBridge = {
+    name: "mem0",
+    version: 1,
+    kind: "api",
+    description: "Import memories from a Mem0 instance (cloud or self-hosted) into Flair",
+    options: {
+        user: {
+            description: "Mem0 user_id whose memories to import.",
+            required: true,
+        },
+        apiKey: {
+            description: "Mem0 API token. Can also be set via MEM0_API_KEY env var.",
+            env: "MEM0_API_KEY",
+            required: true,
+        },
+        baseUrl: {
+            description: "Base URL of the Mem0 API (default: https://api.mem0.ai). Use your self-hosted URL for on-prem.",
+        },
+        maxPages: {
+            description: "Maximum number of pages to fetch (0 = unlimited, for testing/dry-run).",
+        },
+    },
+    import: importMem0,
+    // No export — one-way import; we don't sync back to Mem0.
+};

package/dist/cli.js

@@ -5904,6 +5904,147 @@ memory.command("list")
         console.log(`\nTo backfill: flair reembed --agent ${opts.agent} --stale-only`);
     }
 });
+// ─── flair memory hygiene ────────────────────────────────────────────────────
+// Detect + remove junk memory rows that accumulate over time. Surfaced from
+// the 2026-05-07 manual cleanup (ops-ucyy): rockit had 627 records, ~250 of
+// them were noise — `*-compact-*` ID fragments from an old pipeline, pangram
+// test content ("the quick brown fox..." / "Flair 251 test ..."), and
+// near-empty rows (<25 chars). We did the cleanup ad-hoc with raw curl + jq;
+// this command bundles those patterns + future ones as an operator tool that
+// dry-runs by default.
+//
+// Three pattern categories, each toggle-able:
+//   --pattern compact-id   : ids matching /-compact-/ (legacy pipeline output)
+//   --pattern test-content : content matching pangram / known test strings
+//   --pattern tiny         : content shorter than 25 chars
+//
+// Default is all three, dry-run. Flip --apply to actually delete. Always
+// requires admin pass to read across agent scopes (uses ops API).
+//
+// Federation note: this only deletes on the local instance. ops-esun
+// (federation distributed-delete via tombstones) is the systemic answer for
+// fan-out — until that lands, run `flair memory hygiene` on each peer.
+// Exported for unit testing — keeps the predicate logic separable from
+// the CLI plumbing, ops-API fetching, and confirmation flow.
+export const HYGIENE_TEST_CONTENT_PATTERNS = [
+    /quick brown fox/i,
+    /flair\s*251\s*test/i,
+    /^upgrade-smoke-(pre|post)-marker$/i,
+];
+/** Categorize a single memory row against the enabled hygiene patterns.
+ *  Returns the list of categories the row matches; empty array means clean.
+ *  Pure function — easy to unit test and reason about. */
+export function categorizeForHygiene(row, opts) {
+    const cats = [];
+    if (opts.enabled.has("compact-id") && typeof row.id === "string" && row.id.includes("-compact-")) {
+        cats.push("compact-id");
+    }
+    if (opts.enabled.has("test-content") && typeof row.content === "string" && HYGIENE_TEST_CONTENT_PATTERNS.some((p) => p.test(row.content))) {
+        cats.push("test-content");
+    }
+    if (opts.enabled.has("tiny") && typeof row.content === "string" && row.content.length < opts.tinyThreshold) {
+        cats.push("tiny");
+    }
+    return cats;
+}
+memory.command("hygiene")
+    .description("Detect and (with --apply) remove junk memory rows from the local instance")
+    .option("--apply", "Actually delete the matched rows (default: dry-run)")
+    .option("--pattern <list>", "Comma-separated patterns to match: compact-id,test-content,tiny (default: all)")
+    .option("--tiny-threshold <n>", "Char length below which content is 'tiny'", "25")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--ops-port <port>", "Harper ops API port (default: HTTP - 1)")
+    .action(async (opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
+    if (!adminPass) {
+        console.error("❌ Admin password required (set FLAIR_ADMIN_PASS or HDB_ADMIN_PASSWORD).");
+        process.exit(1);
+    }
+    const enabled = new Set((opts.pattern ?? "compact-id,test-content,tiny").split(",").map((s) => s.trim()).filter(Boolean));
+    const tinyThreshold = Math.max(0, Number(opts.tinyThreshold) || 25);
+    const apply = !!opts.apply;
+    const opsAuth = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+    async function ops(body) {
+        const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: opsAuth },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(60_000),
+        });
+        if (!res.ok) {
+            throw new Error(`ops API failed (${res.status}): ${await res.text().catch(() => "")}`);
+        }
+        return res.json();
+    }
+    // Fetch all rows via ops API. Bypasses /SemanticSearch (vector index) the
+    // same way `flair reembed` does, so this command works even when the
+    // cosine path is broken — exactly the conditions hygiene is most needed.
+    console.log("Scanning Memory table...");
+    const raw = await ops({
+        operation: "search_by_conditions",
+        database: "flair",
+        table: "Memory",
+        operator: "and",
+        conditions: [{ search_attribute: "createdAt", search_type: "greater_than", search_value: "1970-01-01" }],
+        get_attributes: ["id", "agentId", "content", "createdAt"],
+        limit: 100000,
+    });
+    const rows = Array.isArray(raw) ? raw : (raw?.results ?? []);
+    console.log(`  ${rows.length} total memories scanned.`);
+    // Match each pattern. Counts by category, single id list for the delete.
+    const matched = new Map();
+    const allIds = new Set();
+    const hygieneOpts = { enabled: enabled, tinyThreshold };
+    for (const r of rows) {
+        const categories = categorizeForHygiene(r, hygieneOpts);
+        for (const c of categories) {
+            if (!matched.has(c))
+                matched.set(c, new Set());
+            matched.get(c).add(r.id);
+            allIds.add(r.id);
+        }
+    }
+    console.log("");
+    console.log(`Match summary (${apply ? "APPLY" : "dry-run"}):`);
+    const allCategories = ["compact-id", "test-content", "tiny"];
+    for (const c of allCategories) {
+        const n = matched.get(c)?.size ?? 0;
+        const enabledMark = enabled.has(c) ? "✓" : "·";
+        console.log(`  ${enabledMark} ${c.padEnd(13)} ${n.toString().padStart(5)} rows`);
+    }
+    console.log(`  ────────────────────────────`);
+    console.log(`    total unique ${allIds.size.toString().padStart(5)} rows`);
+    if (allIds.size === 0) {
+        console.log("\n✅ Nothing to clean.");
+        return;
+    }
+    if (!apply) {
+        console.log("\n(dry-run) — re-run with --apply to delete the matched rows.");
+        return;
+    }
+    // Delete in chunks (Harper accepts batches of hash_values).
+    const ids = Array.from(allIds);
+    const chunkSize = 200;
+    let deleted = 0;
+    for (let i = 0; i < ids.length; i += chunkSize) {
+        const batch = ids.slice(i, i + chunkSize);
+        const result = await ops({
+            operation: "delete",
+            database: "flair",
+            table: "Memory",
+            hash_values: batch,
+        });
+        const m = /(\d+)\s*of\s*\d+\s*records/.exec(result.message ?? "");
+        deleted += m ? Number(m[1]) : batch.length;
+        process.stdout.write(`\r  Deleting ${deleted}/${ids.length} (${Math.round((deleted / ids.length) * 100)}%)`);
+    }
+    console.log(`\n\n✅ Deleted ${deleted} rows.`);
+    console.log("");
+    console.log("Note: this is a local-instance delete. Federated peers will keep their copies until");
+    console.log("ops-esun (tombstone-based distributed delete) lands. Until then, run `flair memory");
+    console.log("hygiene --apply` on each peer to fan out.");
+});
 // ─── flair search (top-level shortcut) ───────────────────────────────────────
 program
     .command("search <query>")

package/dist/resources/AdminMemory.js

@@ -1,12 +1,37 @@
 import { Resource, databases } from "@harperfast/harper";
 import { layout, htmlResponse, esc } from "./admin-layout.js";
 /**
- * GET /AdminMemory — browse and search memories.
+ * GET /AdminMemory                browse + search memories (list view)
+ * GET /AdminMemory?id=<id>        per-memory detail view with full provenance pane
+ *
+ * Provenance pane surfaces:
+ *   - Identity: id, agentId, subject, contentHash
+ *   - Tags (with source:* / import:* highlighted as origin chips)
+ *   - Lineage: derivedFrom, parentId, supersedes (+ reverse: what supersedes this)
+ *   - Federation: _originatorInstanceId, _syncedFrom, _syncedAt — set by
+ *     Federation sync write path (resources/Federation.ts) when a record
+ *     arrives from a peer. Local-origin memories don't have these.
+ *   - Lifecycle: createdAt, updatedAt, validFrom, validTo, expiresAt,
+ *     archived/archivedAt/archivedBy, promotionStatus/promotedBy/promotedAt
+ *   - Usage: retrievalCount, lastRetrieved
+ *   - Safety: _safetyFlags
+ *
+ * "memory that follows the agent across orchestrators" — the provenance pane
+ * makes that legible: every memory shows where it came from, what it derived
+ * from, what it superseded, and which peer it synced from.
  */
 export class AdminMemory extends Resource {
     async get() {
         const request = this.request;
         const url = new URL(request?.url ?? "http://localhost", "http://localhost");
+        const id = url.searchParams.get("id") ?? "";
+        if (id) {
+            return this.renderDetail(id);
+        }
+        return this.renderList(url);
+    }
+    // ─── List view ─────────────────────────────────────────────────────────────
+    async renderList(url) {
         const query = url.searchParams.get("q") ?? "";
         const subject = url.searchParams.get("subject") ?? "";
         const limit = Math.min(Number(url.searchParams.get("limit") ?? 50), 200);
@@ -34,11 +59,11 @@ export class AdminMemory extends Resource {
         memories.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
         let tableRows = "";
         if (memories.length === 0) {
-            tableRows = `<tr><td colspan="5" class="empty">No memories found${query ? ` matching "${query}"` : ""}.</td></tr>`;
+            tableRows = `<tr><td colspan="6" class="empty">No memories found${query ? ` matching "${query}"` : ""}.</td></tr>`;
         }
         else {
             for (const m of memories) {
-                const preview = (m.content || "").slice(0, 120) + ((m.content || "").length > 120 ? "…" : "");
+                const preview = (m.content || "").slice(0, 100) + ((m.content || "").length > 100 ? "…" : "");
                 const durability = m.durability ?? "standard";
                 const durBadge = durability === "permanent"
                     ? `<span class="badge badge-green">${durability}</span>`
@@ -48,11 +73,18 @@ export class AdminMemory extends Resource {
                 const subjectStr = m.subject ?? "—";
                 const created = m.createdAt?.slice(0, 10) ?? "—";
                 const validity = m.validTo ? `<small>expired ${m.validTo.slice(0, 10)}</small>` : "";
+                // Surface a small "origin" hint in the list — the source:* tag if
+                // present, otherwise blank. Full provenance lives on the detail view.
+                const sourceTag = (m.tags ?? []).find((t) => t.startsWith("source:"));
+                const origin = sourceTag
+                    ? `<span class="badge badge-yellow">${esc(sourceTag.replace("source:", ""))}</span>`
+                    : "—";
                 tableRows += `
           <tr>
-            <td style="max-width:400px">${esc(preview)}</td>
+            <td style="max-width:380px"><a href="/AdminMemory?id=${esc(m.id)}" style="color:#2563eb;text-decoration:none">${esc(preview)}</a></td>
             <td>${durBadge}</td>
             <td>${esc(subjectStr)}</td>
+            <td>${origin}</td>
             <td>${esc(m.agentId ?? "—")}</td>
             <td>${created} ${validity}</td>
           </tr>`;
@@ -78,6 +110,7 @@ export class AdminMemory extends Resource {
             <th>Content</th>
             <th>Durability</th>
             <th>Subject</th>
+            <th>Origin</th>
             <th>Agent</th>
             <th>Created</th>
           </tr>
@@ -89,4 +122,210 @@ export class AdminMemory extends Resource {
     `;
         return htmlResponse(layout("Memory", content, "memory"));
     }
+    // ─── Detail view ───────────────────────────────────────────────────────────
+    async renderDetail(id) {
+        const memDb = databases.flair.Memory;
+        let memory = null;
+        try {
+            memory = await memDb.get(id);
+        }
+        catch { /* table missing or other error */ }
+        if (!memory) {
+            const notFound = `
+        <h1>Memory not found</h1>
+        <p class="subtitle">No memory with id <code>${esc(id)}</code>.</p>
+        <p><a href="/AdminMemory" class="btn btn-primary">Back to memory list</a></p>
+      `;
+            return htmlResponse(layout("Memory not found", notFound, "memory"));
+        }
+        // Lookup memories that supersede this one (reverse of supersedes field).
+        const supersededBy = [];
+        try {
+            for await (const m of memDb.search({ conditions: [{ attribute: "supersedes", comparator: "equals", value: id }] })) {
+                supersededBy.push(m);
+                if (supersededBy.length >= 5)
+                    break;
+            }
+        }
+        catch { /* swallow */ }
+        // Reverse-lookup: memories whose derivedFrom contains this id.
+        // Note: derivedFrom is an array; Harper's contains-on-array search via
+        // search_by_value is used here. If unavailable, leave empty.
+        const derivatives = [];
+        try {
+            for await (const m of memDb.search({ conditions: [{ attribute: "derivedFrom", comparator: "contains", value: id }] })) {
+                derivatives.push(m);
+                if (derivatives.length >= 5)
+                    break;
+            }
+        }
+        catch { /* swallow */ }
+        const content = this.renderProvenancePane(memory, supersededBy, derivatives);
+        return htmlResponse(layout(`Memory ${id.slice(0, 8)}…`, content, "memory"));
+    }
+    // ─── Federation provenance card ────────────────────────────────────────────
+    /**
+     * Surface the federation-write fields stamped by resources/Federation.ts
+     * (lines 392–394) when a record arrived from a peer. Local-origin
+     * memories don't have these fields set; we render an explicit
+     * "local origin" note in that case so the absence is legible.
+     */
+    renderFederationInfo(m) {
+        const orig = m._originatorInstanceId;
+        const from = m._syncedFrom;
+        const at = m._syncedAt;
+        if (!orig && !from && !at) {
+            return "<em style='color:#888'>local origin — not synced from a peer</em>";
+        }
+        const rows = [];
+        if (orig) {
+            rows.push(`<dt style="color:#666">Originator instance</dt><dd><code>${esc(orig)}</code></dd>`);
+        }
+        if (from && from !== orig) {
+            // syncedFrom and originator differ when a hub relayed from a third spoke
+            rows.push(`<dt style="color:#666">Synced from peer</dt><dd><code>${esc(from)}</code> <small style="color:#888">(relayed)</small></dd>`);
+        }
+        else if (from) {
+            rows.push(`<dt style="color:#666">Synced from peer</dt><dd><code>${esc(from)}</code></dd>`);
+        }
+        if (at) {
+            rows.push(`<dt style="color:#666">Synced at</dt><dd>${esc(at)}</dd>`);
+        }
+        return `<dl style="display:grid;grid-template-columns:200px 1fr;gap:8px;margin-top:8px">
+      ${rows.join("\n      ")}
+    </dl>`;
+    }
+    // ─── Provenance pane HTML ──────────────────────────────────────────────────
+    renderProvenancePane(m, supersededBy, derivatives) {
+        const tags = Array.isArray(m.tags) ? m.tags : [];
+        const sourceTag = tags.find((t) => t.startsWith("source:"));
+        const importTag = tags.find((t) => t.startsWith("import:"));
+        const otherTags = tags.filter((t) => !t.startsWith("source:") && !t.startsWith("import:"));
+        const tagChips = [
+            sourceTag ? `<span class="badge badge-yellow" title="origin">${esc(sourceTag)}</span>` : "",
+            importTag ? `<span class="badge badge-blue" title="import path">${esc(importTag)}</span>` : "",
+            ...otherTags.map((t) => `<span class="badge badge-gray">${esc(t)}</span>`),
+        ].filter(Boolean).join(" ");
+        // Lineage links (derivedFrom + parentId + supersedes pointers)
+        const derivedFrom = Array.isArray(m.derivedFrom) ? m.derivedFrom : [];
+        const derivedFromLinks = derivedFrom.length > 0
+            ? derivedFrom.map((d) => `<a href="/AdminMemory?id=${esc(d)}" style="color:#2563eb">${esc(d.slice(0, 12))}…</a>`).join(", ")
+            : "<em style='color:#888'>none</em>";
+        const parentLink = m.parentId
+            ? `<a href="/AdminMemory?id=${esc(m.parentId)}" style="color:#2563eb">${esc(m.parentId.slice(0, 12))}…</a>`
+            : "<em style='color:#888'>none</em>";
+        const supersedesLink = m.supersedes
+            ? `<a href="/AdminMemory?id=${esc(m.supersedes)}" style="color:#2563eb">${esc(m.supersedes.slice(0, 12))}…</a>`
+            : "<em style='color:#888'>nothing — this is an original</em>";
+        const supersededByLinks = supersededBy.length > 0
+            ? supersededBy.map((s) => `<a href="/AdminMemory?id=${esc(s.id)}" style="color:#2563eb">${esc(s.id.slice(0, 12))}…</a>`).join(", ")
+            : "<em style='color:#888'>nothing — this is current</em>";
+        const derivativesLinks = derivatives.length > 0
+            ? derivatives.map((d) => `<a href="/AdminMemory?id=${esc(d.id)}" style="color:#2563eb">${esc(d.id.slice(0, 12))}…</a>`).join(", ")
+            : "<em style='color:#888'>none</em>";
+        // Promotion details (if promoted)
+        const promotionInfo = m.promotionStatus
+            ? `<dl style="display:grid;grid-template-columns:140px 1fr;gap:8px;margin-top:8px">
+           <dt style="color:#666">Status</dt><dd>${esc(m.promotionStatus)}</dd>
+           ${m.promotedAt ? `<dt style="color:#666">Promoted at</dt><dd>${esc(m.promotedAt)}</dd>` : ""}
+           ${m.promotedBy ? `<dt style="color:#666">Promoted by</dt><dd>${esc(m.promotedBy)}</dd>` : ""}
+         </dl>`
+            : "<em style='color:#888'>not promoted</em>";
+        // Archive details
+        const archiveInfo = m.archived
+            ? `<dl style="display:grid;grid-template-columns:140px 1fr;gap:8px;margin-top:8px">
+           <dt style="color:#666">Archived at</dt><dd>${esc(m.archivedAt ?? "—")}</dd>
+           <dt style="color:#666">Archived by</dt><dd>${esc(m.archivedBy ?? "—")}</dd>
+         </dl>`
+            : "<em style='color:#888'>active</em>";
+        const safetyFlags = Array.isArray(m._safetyFlags) ? m._safetyFlags : [];
+        const safetyDisplay = safetyFlags.length > 0
+            ? safetyFlags.map((f) => `<span class="badge badge-yellow">${esc(f)}</span>`).join(" ")
+            : "<em style='color:#888'>clean</em>";
+        return `
+      <div style="margin-bottom:16px">
+        <a href="/AdminMemory" style="color:#666;text-decoration:none;font-size:0.9em">← Back to memory list</a>
+      </div>
+
+      <h1>Memory ${esc(m.id.slice(0, 8))}…</h1>
+      <p class="subtitle">
+        agentId: <code>${esc(m.agentId ?? "—")}</code> ·
+        subject: ${m.subject ? `<code>${esc(m.subject)}</code>` : "—"}
+      </p>
+
+      <div class="card">
+        <h3>Content</h3>
+        <p style="white-space:pre-wrap;font-family:ui-monospace,SF Mono,monospace;font-size:0.95em;line-height:1.5;margin-top:8px">${esc(m.content ?? "")}</p>
+        ${m.summary ? `<div style="margin-top:12px;padding-top:12px;border-top:1px solid #eee"><strong style="color:#666;font-size:0.85em">SUMMARY</strong><p style="margin-top:4px">${esc(m.summary)}</p></div>` : ""}
+      </div>
+
+      <div class="card">
+        <h3>Tags</h3>
+        <div style="margin-top:8px;display:flex;gap:6px;flex-wrap:wrap">
+          ${tagChips || "<em style='color:#888'>untagged</em>"}
+        </div>
+      </div>
+
+      <div class="card">
+        <h3>Lineage</h3>
+        <dl style="display:grid;grid-template-columns:200px 1fr;gap:10px;margin-top:8px">
+          <dt style="color:#666">Derived from</dt><dd>${derivedFromLinks}</dd>
+          <dt style="color:#666">Parent</dt><dd>${parentLink}</dd>
+          <dt style="color:#666">Supersedes</dt><dd>${supersedesLink}</dd>
+          <dt style="color:#666">Superseded by</dt><dd>${supersededByLinks}</dd>
+          <dt style="color:#666">Derivatives (downstream)</dt><dd>${derivativesLinks}</dd>
+          ${m.sessionId ? `<dt style="color:#666">Session</dt><dd><code>${esc(m.sessionId)}</code></dd>` : ""}
+        </dl>
+      </div>
+
+      <div class="card">
+        <h3>Lifecycle</h3>
+        <dl style="display:grid;grid-template-columns:200px 1fr;gap:10px;margin-top:8px">
+          <dt style="color:#666">Durability</dt><dd>${esc(m.durability ?? "standard")}</dd>
+          <dt style="color:#666">Created</dt><dd>${esc(m.createdAt ?? "—")}</dd>
+          <dt style="color:#666">Updated</dt><dd>${esc(m.updatedAt ?? "—")}</dd>
+          <dt style="color:#666">Valid from</dt><dd>${esc(m.validFrom ?? "—")}</dd>
+          <dt style="color:#666">Valid to</dt><dd>${esc(m.validTo ?? "still valid")}</dd>
+          <dt style="color:#666">Expires</dt><dd>${esc(m.expiresAt ?? "never")}</dd>
+        </dl>
+      </div>
+
+      <div class="card">
+        <h3>Federation</h3>
+        ${this.renderFederationInfo(m)}
+      </div>
+
+      <div class="card">
+        <h3>Promotion</h3>
+        ${promotionInfo}
+      </div>
+
+      <div class="card">
+        <h3>Archive</h3>
+        ${archiveInfo}
+      </div>
+
+      <div class="card">
+        <h3>Usage</h3>
+        <dl style="display:grid;grid-template-columns:200px 1fr;gap:10px;margin-top:8px">
+          <dt style="color:#666">Retrievals</dt><dd>${m.retrievalCount ?? 0}</dd>
+          <dt style="color:#666">Last retrieved</dt><dd>${esc(m.lastRetrieved ?? "—")}</dd>
+        </dl>
+      </div>
+
+      <div class="card">
+        <h3>Safety</h3>
+        ${safetyDisplay}
+      </div>
+
+      <div class="card" style="background:#f8f9fa">
+        <h3 style="color:#666;font-size:0.9em">RAW IDENTITY</h3>
+        <dl style="display:grid;grid-template-columns:200px 1fr;gap:6px;margin-top:8px;font-family:ui-monospace,SF Mono,monospace;font-size:0.85em">
+          <dt style="color:#666">id</dt><dd>${esc(m.id)}</dd>
+          <dt style="color:#666">contentHash</dt><dd>${esc(m.contentHash ?? "—")}</dd>
+          <dt style="color:#666">visibility</dt><dd>${esc(m.visibility ?? "private")}</dd>
+        </dl>
+      </div>
+    `;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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",
   "license": "Apache-2.0",