@tpsdev-ai/flair 0.9.0 → 0.10.1

package/README.md

@@ -4,9 +4,9 @@
 [![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)
 
-> **The memory system that gives agents a durable identity, not just durable facts. Federated. Crypto-isolated. Yours.**
+> **The identity and memory substrate for AI agents. Crypto-pinned. Federated. Self-hosted.**
 
-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.
+Flair is the **identity + memory substrate for AI agents**. Cryptographic per-agent identity (Ed25519). Soul as a first-class primitive, separate from memory. Federation across hosts (hub/spoke). Same agent, every orchestrator — memory follows.
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
@@ -17,7 +17,7 @@ Most agent memory systems store *facts*. Flair stores facts AND the agent's iden
 │  Codex CLI    ─┼─[ flair-mcp ]─┐                                 │
 │  Gemini CLI   ─┤               │                                 │
 │  Continue.dev ─┤               │   ┌──────────────────────┐      │
-│  Goose        ─┘               ├─▶ │  Flair (rockit)      │      │
+│  Goose        ─┘               ├─▶ │  Flair (self-hosted) │      │
 │  LangGraph   ─[ langgraph-flair ]──│  Ed25519 / HNSW /    │      │
 │  OpenClaw    ─[ openclaw-flair  ]──│  Soul + Memory       │      │
 │  n8n         ─[ n8n-nodes-flair ]──└──────────┬───────────┘      │
@@ -42,22 +42,18 @@ Most agent memory systems store *facts*. Flair stores facts AND the agent's iden
 
 ![Flair cross-orchestrator: one agent, one memory store, three MCP-capable CLIs](docs/assets/flair-cross-orchestrator.gif)
 
-Same Ed25519 identity, same memory store, three different MCP-capable CLIs (Claude Code, Codex CLI, Gemini CLI). A memory written from one is immediately retrievable from the next. This is the load-bearing differentiation vs vendor-locked memory systems — your agent's identity and history aren't bound to a single orchestrator's runtime.
+Same Ed25519 identity, same memory store, three different MCP-capable CLIs (Claude Code, Codex CLI, Gemini CLI). A memory written from one is immediately retrievable from the next. Your agent's identity and history aren't bound to a single orchestrator's runtime.
 
 ## How Flair compares
 
 | | 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.
+Four rows where Flair holds a cell no other system holds cleanly today. Parity rows (license, self-host, semantic search) are table-stakes for this neighborhood — Mem0, Honcho, and Letta are all open-source and self-hostable — so they're omitted to keep the moat visible.
 
 The honest gaps:
 
@@ -71,11 +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 an on-demand curation surface today: `flair rem rapid`. Scheduled nightly REM is in the [FLAIR-NIGHTLY-REM spec](specs/FLAIR-NIGHTLY-REM.md) and partially built.
+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 rem rapid`** (ships now) — on-demand reflection. `--focus {lessons_learned, patterns, decisions, errors}` mirrors Dreams' `instructions` parameter. Outputs *candidates*, not a wholesale store swap.
-- **`flair rem candidates` / `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id>`** (ship now) — review and promote distilled candidates with required rationale.
-- **`flair rem nightly`** (planned, P0 for 1.0) — scheduled automation with pre-cycle snapshot, `rem restore <date>` rollback, trust-tier filtering. Spec'd; not yet implemented.
+- **`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 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 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.
 
 The substantive difference is the **promotion contract**:
 
@@ -83,7 +81,7 @@ The substantive difference is the **promotion contract**:
 |---|---|---|
 | **Output** | New memory store — accept or discard | Staged candidates — per-candidate decision |
 | **Promotion gate** | None — accept the whole store | `flair rem promote <id> --rationale "<why>"` |
-| **Reversibility** | Input store is never modified (real safety property) | In-place modifications; nightly snapshot/restore is on the roadmap |
+| **Reversibility** | Input store is never modified (real safety property) | Pre-cycle snapshot + `rem restore <date> --apply` (rewinds Harper state, takes a pre-restore snapshot too) |
 | **Where it runs** | Anthropic Managed Agents (SaaS, Anthropic models only) | Self-hosted, any model |
 
 Dreams is easier to start with — one API call, and the input-never-modified contract gives you a clean rollback by simply not accepting the output. REM is the more granular surface — per-candidate decisions with required rationale — for operators who want to merge what's right and reject what's wrong on the same nightly cycle. Both are legitimate choices; the right one depends on whether you want store-level or candidate-level review.
@@ -148,7 +146,7 @@ Not all memories are equal:
 Memories can be time-bounded with `validFrom` and `validTo` fields. Expired memories are excluded from search and bootstrap automatically — no manual cleanup.
 
 ### Relationship Graph
-Entity-to-entity triples with temporal bounds. Model structured knowledge — "Flint works-with Anvil since 2024-01-01" — queryable alongside semantic memory.
+Entity-to-entity triples with temporal bounds. Model structured knowledge — "Alice works-with Bob since 2024-01-01" — queryable alongside semantic memory.
 
 ### Real-Time Feeds
 Subscribe to memory or soul changes via WebSocket/SSE. Useful for dashboards, cross-agent sync, or audit trails.
@@ -360,7 +358,7 @@ flair/
 - **Harper-native** — No Express, no middleware frameworks. Harper IS the runtime.
 - **In-process embeddings** — Native [nomic-embed-text](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF) (768 dimensions) via [llama.cpp](https://github.com/ggerganov/llama.cpp). Runs on CPU or GPU (Metal, CUDA). No API calls, no OpenAI key needed.
 - **Schema-driven** — GraphQL schemas with `@table @export` auto-generate REST CRUD. Custom resources extend behavior (durability guards, auto-embedding, search).
-- **Zero admin tokens on disk** — Admin credentials come from the `HDB_ADMIN_PASSWORD` environment variable only. Never stored on the filesystem.
+- **Admin credentials** — `flair init` auto-generates an admin password stored at `~/.flair/admin-pass` (mode 0600). Can also be set via `HDB_ADMIN_PASSWORD`. See [SECURITY.md](SECURITY.md) for the full model.
 
 ## Deployment
 
@@ -392,9 +390,9 @@ FLAIR_URL=https://your-server:19926 flair agent add mybot
 
 Good for teams with multiple machines or always-on agents.
 
-### Harper Fabric (coming soon)
+### Harper Fabric
 
-Managed multi-region deployment via [Harper Fabric](https://www.harperdb.io/). Data replication, automatic failover, web dashboard. Enterprise scale without ops overhead.
+Deploy Flair on [Harper Fabric](https://www.harperdb.io/) for managed hosting with multi-region replication and failover. Federation runs against Harper Fabric hubs (e.g. `flair.your-org.harperfabric.com`) — pair your local instance to sync memories across nodes.
 
 ## Security
 
@@ -403,7 +401,7 @@ See [SECURITY.md](SECURITY.md) for the full security model, threat analysis, and
 **Key points:**
 - Ed25519 cryptographic identity — agents sign every request
 - Collection-level data isolation — agents can't read each other's memories
-- Admin credentials never stored on disk — environment variables only
+- Admin password auto-generated on init, stored at `~/.flair/admin-pass` (mode 0600)
 - Key rotation via `flair agent rotate-key`
 - Cross-agent access requires explicit grants