@tpsdev-ai/flair 0.21.0 → 0.22.1

package/README.md

@@ -67,13 +67,13 @@ If you need any of those specifically, use them. If you need crypto-pinned ident
 
 Anthropic shipped [Claude Dreams](https://platform.claude.com/docs/en/managed-agents/dreams) (research preview, April 2026) — async pipeline that reads a memory store + session transcripts and produces a curated output store: duplicates merged, stale entries replaced, insights surfaced. Validates the category: agent memory accumulates drift and needs cleanup.
 
-Flair ships both the on-demand curation surface (`flair rem rapid`) AND the scheduled nightly cycle in v0.9.0, per the [FLAIR-NIGHTLY-REM spec](specs/FLAIR-NIGHTLY-REM.md).
+Flair ships both the on-demand curation surface (`flair rem rapid`) AND the scheduled nightly cycle, per the [FLAIR-NIGHTLY-REM spec](specs/FLAIR-NIGHTLY-REM.md) and its [in-process distillation slice](specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md). Config recipe (Ollama zero-key default, hosted-provider egress warning, clustered-deploy rules): [`docs/rem.md`](docs/rem.md).
 
-- **`flair rem rapid`** — on-demand reflection. `--focus {lessons_learned, patterns, decisions, errors}` mirrors Dreams' `instructions` parameter. Outputs *candidates*, not a wholesale store swap.
+- **`flair rem rapid`** — reflects and distills server-side by default, staging candidates in one bounded call. `--focus {lessons_learned, patterns, decisions, errors}` mirrors Dreams' `instructions` parameter. `--prompt-only` falls back to the bring-your-own-model handoff. Outputs *candidates*, not a wholesale store swap.
 - **`flair rem candidates` / `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id>`** — review and promote distilled candidates with required rationale.
-- **`flair rem nightly enable [--at HH:MM]`** — scheduled automation via platform-native scheduler (launchd / systemd). Pre-cycle snapshot to `~/.flair/snapshots/<agent>/<iso>.tar.gz`. Maintenance step (soft-delete expired + soft-archive stale). Audit log to `~/.flair/logs/rem-nightly.jsonl`. `flair rem pause` / `resume` for emergency stop.
+- **`flair rem nightly enable [--at HH:MM]`** — scheduled automation via platform-native scheduler (launchd / systemd). Pre-cycle snapshot to `~/.flair/snapshots/<agent>/<iso>.tar.gz`. Maintenance (soft-delete expired + soft-archive stale) and distillation (staged candidates) both run each cycle. Audit log to `~/.flair/logs/rem-nightly.jsonl`. `flair rem pause` / `resume` for emergency stop.
 - **`flair rem restore <date> --apply`** — rewinds Harper state to a snapshot. Takes a pre-restore snapshot of current state first, so the rewind itself is reversible.
-- *Slice-3 (1.1)* — automated server-side distillation (requires pluggable LLM provider), trust-tier filter on REM input, cross-agent restore. Until then, distillation is operator-triggered via `flair rem rapid` followed by manual promote/reject.
+- *Next* — trust-tier filter on REM input, cross-agent restore. Until the trust-tier arc lands, the input filter stays scope-based (own agent, non-archived, non-permanent, scope window); the structural safety net is unchanged either way — candidates are staged, never auto-promoted.
 
 The substantive difference is the **promotion contract**:
 
@@ -94,7 +94,7 @@ An agent that can't remember what it learned yesterday, can't prove who it is to
 
 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.
+- **Identity** — Ed25519 key pairs. Agents sign every request. No passwords, no API keys, no shared secrets. Write isolation (no agent can write as another) is enforced at the server, not by client convention; reads are open within the org for non-private memories by design (see [SECURITY.md](SECURITY.md)).
 - **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.
 
@@ -177,6 +177,9 @@ Passive extraction of entities from memory content on write. Entities are indexe
 ### Memory Bridges
 Pluggable import/export to foreign memory systems. Every agent-memory format (agentic-stack, Mem0, Letta, Anthropic memory, the next viral one) shouldn't need its own Flair PR. Bridges give you one contract with two shapes — a YAML descriptor for file-format targets or a code plugin for API targets — and a scaffold/test loop that lets an agent ship a working adapter in one pass. See [docs/bridges.md](docs/bridges.md).
 
+### Embedding benchmarks (`flair-bench`)
+A standalone benchmark you can run anywhere — no Flair install, no server, just Node and a GGUF file. It ships the same 126-query recall corpus and scoring Flair's own CI gates on, so its numbers are directly comparable: benchmark candidate embedding models (`--model-file`, batchable), get a model recommendation for the host you're on backed by the numbers it just measured (`recommend`), and optionally save a redacted, shareable result (`--share`) — including a `--label` for tagging host classes when characterizing fleet hardware. See [packages/flair-bench](packages/flair-bench/README.md).
+
 ## Quick Start
 
 ### Prerequisites
@@ -409,9 +412,9 @@ Auth is Ed25519 — sign `agentId:timestamp:nonce:METHOD:/path` with your privat
 
 ### Auth across surfaces
 
-The default, secure path everywhere is **Ed25519 per-agent**: each agent holds its own key (`~/.flair/keys/<agent>.key`), signs every request, and the server refuses cross-agent reads. The CLI, the `flair-mcp` server, and the OpenClaw / pi / Hermes plugins all use it.
+The default, secure path everywhere is **Ed25519 per-agent**: each agent holds its own key (`~/.flair/keys/<agent>.key`) and signs every request. That guarantees write isolation (no agent can write as another) and identity-verified reads — it does **not** mean cross-agent reads are refused: within one Flair instance, any verified agent can read any other agent's non-private memory by design (open-within-org read; the hard boundary is the federation edge, not intra-instance reads — see [SECURITY.md](SECURITY.md)). The CLI, the `flair-mcp` server, and the OpenClaw / pi / Hermes plugins all use this model.
 
-One exception: the **`n8n-nodes-flair`** community node authenticates with the Harper **admin password** (Basic auth), which grants **whole-instance read/write** access — not per-agent isolation. That's acceptable only on a single-tenant, operator-controlled n8n with trusted workflow inputs; otherwise prefer the CLI/SDK Ed25519 path. Full breakdown in **[docs/auth.md](docs/auth.md#auth-across-surfaces-read-this-first)**.
+One exception: the **`n8n-nodes-flair`** community node authenticates with the Harper **admin password** (Basic auth), which bypasses agent scoping entirely — including read of other agents' `visibility: private` memories and write-as-anyone, not just the org-wide non-private reads an Ed25519 identity already gets. That's acceptable only on a single-tenant, operator-controlled n8n with trusted workflow inputs; otherwise prefer the CLI/SDK Ed25519 path. Full breakdown in **[docs/auth.md](docs/auth.md#auth-across-surfaces-read-this-first)**.
 
 ## Architecture
 

package/SECURITY.md

@@ -34,8 +34,23 @@ built-in HTTP Basic auth:
 Authorization: Basic <base64(admin:password)>
 ```
 
-The admin password is set via `HDB_ADMIN_PASSWORD` environment variable
-at Harper startup. **It is never stored on the filesystem by Flair.**
+The admin password is generated on `flair init` and stored at
+`~/.flair/admin-pass` (mode `0600`, owner-only) — it can also be set
+explicitly via `--admin-pass-file`, `FLAIR_ADMIN_PASS`, or
+`HDB_ADMIN_PASSWORD`. It is never printed to the console. See
+[docs/secrets-and-keys.md](docs/secrets-and-keys.md) for the full
+precedence and rotation model.
+
+The Harper **operations API** is the admin/management surface. Network
+requests to it require admin Basic auth: Flair ships with
+`authorizeLocal: false`, so an unauthenticated loopback request is
+rejected (`401`) instead of being auto-elevated to super_user. The same
+API is also reachable over a Unix **domain socket**
+(`~/.flair/data/operations-server`, owner-write-only), which Harper
+treats as an inherent local-admin channel — a request over the socket is
+authorized as super_user **without** credentials. This is by design (the
+admin-password rotation flow relies on it) and is constrained to the box
+owner; see Threats NOT Mitigated below.
 
 ## Data Scoping
 
@@ -115,6 +130,13 @@ public key in Flair, and backs up the old key as `<agentId>.key.bak`.
   process could extract them.
 - **Network sniffing:** Flair uses HTTP by default. Use HTTPS in
   production or restrict to localhost.
+- **Same-OS-user ops-API socket access:** the operations-API domain
+  socket (`operations-server`, owner-write-only) is an unauthenticated
+  super_user channel by Harper design — any process running as the box
+  owner can perform admin operations through it (the admin-password
+  rotation flow uses this path). Owner-write permissions keep it
+  unreachable by other OS users, co-tenants, and the network; isolate
+  untrusted workloads to separate OS users.
 
 ## Recommendations
 

package/config.yaml

@@ -12,11 +12,38 @@ graphqlSchema:
 jsResource:
   files: dist/resources/*.js
 
-'harper-fabric-embeddings':
-  package: 'harper-fabric-embeddings'
-  modelName: nomic-embed-text
+# Phase 1 (flair#504): embeddings now run through Harper's native
+# models.embed() facade, backed by harper-fabric-embeddings registered as the
+# `embedding` backend. That registration is NOT configured here, and (as of
+# flair#694) is no longer config-driven anywhere: a `models:` block in THIS
+# file would silently never be read (this application always loads with
+# `isRoot: false` — components/componentLoader.ts gates `bootstrapModels()`
+# on `isRoot`), and the earlier fix for that — reasserting the block into the
+# Harper INSTANCE-ROOT config via the HARPER_CONFIG env var on every spawn —
+# turned out to PERSIST that block into harper-config.yaml, which an
+# older/downgraded build's boot (never having set the env var) would tear
+# down to an invalid empty shell and refuse to boot against (flair#694; see
+# flair#695 for the invariant this violated). The registration now happens
+# in-process instead: `dist/resources/embeddings-boot.js` (built from
+# resources/embeddings-boot.ts, loaded by the `jsResource` glob below like
+# every other file under resources/) calls harper-fabric-embeddings'
+# `register()` factory directly on every boot — nothing is ever written to
+# the config file, so there is nothing for a downgrade to trip over. This
+# also means a `package:`-style sub-component entry
+# (`'harper-fabric-embeddings': { package: ... }`, which used to sit here and
+# drove `handleApplication`) still must not be reintroduced alongside it —
+# that hook populates a SEPARATE raw-API engine, not `models.embed()`, and
+# running both would double-init (two separate EmbeddingEngine instances:
+# one unused, one backing models.embed).
 
 authentication:
-  # Default secure. Set to false for local development only.
-  authorizeLocal: true
+  # Default secure (flair#654): a credential-less loopback request to the
+  # Harper ops API (:9925) is no longer auto-authorized as super_user. Local
+  # admin operations now require a real credential — ~/.flair/admin-pass
+  # (written by `flair init`), --admin-pass, or FLAIR_ADMIN_PASS. flair's own
+  # application-layer resources were already immune to this forgery (#655's
+  # credential-evidence gate); this closes the remaining gap below it, in the
+  # raw Harper ops API itself. Set true only for local development, at your
+  # own risk.
+  authorizeLocal: false
   enableSessions: true