@tpsdev-ai/flair 0.25.0 → 0.25.1

package/README.md

@@ -134,6 +134,15 @@ flair memory search "native addon loading in sandboxed runtimes"
 # → [0.67] Harper v5 sandbox blocks node:module but process.dlopen works
 ```
 
+### Trust-Graded Recall
+Recall can carry an opt-in **trust-evidence block** per result — provenance (verified vs claimed author), usage signal, freshness/validity, supersession — so an agent weighs *what to trust*, not just *what matched*. On top of it:
+
+- **Confidence bands** (`matchQuality`): each result is labeled `strong` / `moderate` / `breadcrumb` from its absolute similarity — a weak-but-relevant hit is taken for what it is, not mistaken for a confident one.
+- **First-class abstention** (`abstain`): when nothing clears a confidence floor, recall returns an honest "no memory covers this" verdict instead of the N weakest matches.
+- **Citation-on-write** (`usedMemoryIds`) + **`record_usage`**: report which memories actually grounded an answer — a deduped, principal-bound usage signal (honest evidence, never retrieval-popularity) that strengthens future recall.
+
+Opt-in and additive (`includeTrust` / `abstain` on the recall path) — off by default, byte-identical when unused. Reachable today via the authenticated HTTP API and the native `/mcp` tools; first-class exposure in the `flair` CLI, `@tpsdev-ai/flair-client`, and the `flair-mcp` bridge is a follow-up. Full arc in the [CHANGELOG](CHANGELOG.md) (flair#744).
+
 ### Tiered Durability
 Not all memories are equal:
 
@@ -340,7 +349,7 @@ Add to your `CLAUDE.md`:
 
     At the start of every session, run mcp__flair__bootstrap before responding.
 
-Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The MCP server exposes `memory_store`, `memory_search`, `memory_get`, `memory_delete`, `bootstrap`, `soul_set`, `soul_get`.
+Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The `flair-mcp` server — the bridge these CLIs connect to — exposes `memory_store`, `memory_search`, `memory_update`, `memory_get`, `memory_delete`, `relationship_store`, `bootstrap`, `soul_set`, `soul_get`, `flair_workspace_set`, and `flair_orgevent`. (Flair's in-Harper native `/mcp` surface is a separate, still-experimental tool set with `attention` + `record_usage` — see Trust-Graded Recall above.)
 
 For per-CLI config snippets (Gemini CLI's `~/.gemini/settings.json`, Codex CLI's `~/.codex/config.toml`, etc.), see **[docs/mcp-clients.md](docs/mcp-clients.md)**. For a deeper Claude Code walk-through with `CLAUDE.md` patterns, see [docs/claude-code.md](docs/claude-code.md).
 
@@ -353,7 +362,7 @@ Use Flair as the memory backend for n8n's AI Agent. Same memories readable from
 @tpsdev-ai/n8n-nodes-flair
 ```
 
-Two nodes ship: **Flair Chat Memory** (Memory port, conversation buffer) and **Flair Search** (Tool port, semantic search + get-by-subject). Setup walkthrough, subject/sessionId patterns, and security guidance in **[docs/n8n.md](docs/n8n.md)**.
+Three nodes ship: **Flair Chat Memory** (Memory port, conversation buffer), **Flair Search** (Tool port, semantic search + get-by-subject), and **Flair Write** (Tool port, store memories). Setup walkthrough, subject/sessionId patterns, and security guidance in **[docs/n8n.md](docs/n8n.md)**.
 
 ### JavaScript / TypeScript (Client Library)
 
@@ -541,13 +550,13 @@ Flair is in active development and daily use. We dogfood it — the agents that
 - ✅ Web admin UI (principals, connectors, IdPs, instance config)
 - ✅ Federation (hub-and-spoke sync with signed requests and pairing tokens)
 - ✅ OpenClaw memory plugin
-- ✅ MCP server for Claude Code / Cursor / Windsurf
+- ✅ MCP server for Claude Code / Cursor / Codex / Gemini CLI
 - ✅ Lightweight client library (`@tpsdev-ai/flair-client`)
 - ✅ Portable agent identity (export/import between instances)
 - ✅ `flair --version`, `flair upgrade`
+- ✅ First-run soul wizard (interactive personality setup)
 
 **What's next:**
-- [ ] First-run soul wizard (interactive personality setup)
 - [ ] Git-backed memory sync
 - [ ] Encryption at rest (opt-in AES-256-GCM per memory)
 - [ ] Harper Fabric deployment (managed multi-office)

package/dist/cli.js

@@ -1641,6 +1641,23 @@ export function decideAfterVerify(result, previousVersion) {
     if (result.ok)
         return { kind: "ok" };
     const reason = result.error ?? "post-restart verification failed";
+    // A HEALTHY instance whose ONLY failure was that the verifier couldn't
+    // authenticate (401/403) is demonstrably UP: the public /Health answered
+    // 2xx AND the server responded to the authenticated probe — it rejected our
+    // credentials, it did not fail to respond. A version we couldn't READ is not
+    // grounds to roll back a RUNNING instance. Rolling back here is destructive
+    // AND self-defeating — the rollback's own re-verify hits the identical
+    // missing-credential wall, producing the false "ROLLBACK ALSO FAILED / state
+    // UNKNOWN" for an instance that was healthy the whole time. (The real
+    // incident: /HealthDetail became a verified-read in flair#747, so a machine
+    // with no admin-pass/agent key authenticates fine against the pre-upgrade
+    // version but not post-restart — the pre-flight credential check can't
+    // anticipate a version that changes /HealthDetail's auth requirement.)
+    // Report it as up-but-unverified and NEVER roll back. This supersedes
+    // flair#741 fix #3's "prefer the known-good version" default, which the
+    // incident proved wrong for a healthy instance.
+    if (isCredentialOnlyFailure(result))
+        return { kind: "healthy-unverified", reason };
     if (!previousVersion)
         return { kind: "cannot-rollback", reason };
     return { kind: "rollback", reason, toVersion: previousVersion };
@@ -8352,18 +8369,22 @@ program
         console.log(`✅ verified: healthy, authenticated${verify.version ? `, running ${verify.version}` : ""}`);
         return;
     }
-    console.error(`❌ post-restart verification failed: ${verdict.reason}`);
-    if (isCredentialOnlyFailure(verify)) {
-        // flair#741 fix #3: a responding server that rejects the verifier's
-        // credentials proves the instance is UP — it is not evidence the
-        // upgrade itself broke anything. Say so explicitly instead of leaving
-        // the reader to infer it from the raw error text. Rollback still
-        // proceeds below (a credential check that worked pre-upgrade — see
-        // the pre-flight above — and stopped working mid-run is an edge case
-        // ambiguous enough that "prefer the known-good version" is still the
-        // safer default), but the reason for it is now honest.
-        console.error("   The instance is up and responded — the verifier could not authenticate. This is not a sign the upgrade broke anything.");
+    // flair#741 follow-through: a healthy instance the verifier just couldn't
+    // authenticate against. The upgrade SUCCEEDED — the new version's server is
+    // up (public /Health passed); we simply couldn't read its version over the
+    // authenticated /HealthDetail. Report the caveat and STOP — never roll back
+    // a running instance over a credentials gap. (decideAfterVerify only
+    // returns this for isCredentialOnlyFailure(verify), so the old
+    // "print an honest note but roll back anyway" branch that used to sit below
+    // is gone — that credentials case can no longer reach the rollback path.)
+    if (verdict.kind === "healthy-unverified") {
+        console.log(`✅ upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}.`);
+        console.log(`   The version could not be verified — the checker couldn't authenticate to /HealthDetail (${verdict.reason}).`);
+        console.log("   The server is confirmed running (public /Health passed); this is a verification gap, not an upgrade failure — nothing was rolled back.");
+        console.log("   To enable full post-upgrade verification: set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key.");
+        return;
     }
+    console.error(`❌ post-restart verification failed: ${verdict.reason}`);
     if (verdict.kind === "cannot-rollback") {
         console.error("   Cannot roll back automatically: the previously-installed @tpsdev-ai/flair version is unknown.");
         console.error("   Check the instance now: flair doctor");

package/package.json

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