@tpsdev-ai/flair 0.26.0 → 0.27.1

package/docs/entity-vocabulary.md

@@ -0,0 +1,109 @@
+# Entity Vocabulary
+
+The **attention plane** — an agent seeing what its teammates are actively touching, and
+where its own work collides with theirs — needs one thing to work at all: a single,
+consistent way to name the "things" (repos, issues, customers, subsystems, people, agents)
+that memories, workspace state, org events, and relationships all reference. Without it,
+"what touches entity E" can never be an indexed lookup — it degenerates into fuzzy string
+matching across free-text fields.
+
+This document is that convention. It's written down and enforced by a small validator
+(`resources/entity-vocab.ts`) **before** anything is built on top of it, because three
+surfaces already consume entity strings today (the `Relationship` graph's `subject`/`object`,
+and the new `entities` fields on `WorkspaceState`/`OrgEvent`/`Memory`), plus a future
+attention query and any future MCP scope field — retrofitting a divergent vocabulary later
+is expensive.
+
+> This doc covers the vocabulary and validator only — the foundation slice of the attention
+> plane (flair#675). The attention query ("what touches entity E in the last N days") and
+> bootstrap collision surfacing are separate, later slices. See `FLAIR-ATTENTION-PLANE.md`
+> for the full design.
+
+## The form
+
+An entity is a single string: `type:value`.
+
+- **type** — lowercase, drawn from a **closed** set (below). Not user-extensible at write
+  time; new types are added deliberately, by changing `ENTITY_TYPES` in
+  `resources/entity-vocab.ts` (and this doc) in the same change.
+- **value** — a stable identifier whose grammar depends on the type (see table).
+
+Matching is **exact on the full string** — `repo:tpsdev-ai/flair` and
+`repo:tpsdev-ai/flair-mcp` are unrelated entities, not prefix-related. This is what makes the
+indexed `entities: [String] @indexed` fields a plain equality lookup rather than a scan.
+
+## The closed type set
+
+| Type | Form | Example | Value grammar |
+|------|------|---------|---------------|
+| `repo` | `repo:<owner>/<name>` | `repo:tpsdev-ai/flair` | Two lowercase path segments (alnum + `.`/`-`/`_` internal separators) joined by exactly one `/`. |
+| `issue` | `issue:<repo>#<n>` | `issue:tpsdev-ai/flair#504` | A valid `repo` value, then `#`, then a positive integer with no leading zero. |
+| `customer` | `customer:<slug>` | `customer:acme` | A lowercase slug (alnum segments joined by single `-`/`_`). |
+| `subsystem` | `subsystem:<slug>` | `subsystem:embeddings` | Same slug grammar as `customer`. |
+| `agent` | `agent:<agentId>` | `agent:flint` | Same slug grammar — the agent's registered id. |
+| `person` | `person:<id>` | `person:nathan` | Same slug grammar. |
+
+Rules that apply across every type:
+
+- The type prefix is **always lowercase** — `Repo:x`, `CUSTOMER:x` etc. are invalid (not a
+  case-insensitive match against the closed set — they simply aren't in it).
+- No leading/trailing whitespace anywhere in the string.
+- No empty type or empty value (`:acme`, `repo:`, `repo` with no colon are all invalid).
+- Slugs never have leading/trailing/doubled separators (`-embeddings`, `embeddings-`,
+  `embed--dings` are all invalid).
+
+## The validator
+
+`resources/entity-vocab.ts` is the single source of truth — every write path that persists
+an `entities` value validates against it, not a local reimplementation of the grammar.
+
+```ts
+import { isValidEntity, validateEntities, invalidEntitiesResponse } from "./entity-vocab.js";
+
+isValidEntity("repo:tpsdev-ai/flair");      // true
+isValidEntity("project:flair");             // false — "project" isn't in the closed type set
+isValidEntity("Customer:Acme");             // false — uppercase type and value both reject
+
+validateEntities(["repo:tpsdev-ai/flair", "bogus"]);
+// => { valid: false, invalid: ["bogus"] }
+
+validateEntities(undefined);
+// => { valid: true, invalid: [] }  — the field is additive/optional; absence is not an error
+```
+
+`invalidEntitiesResponse(entities)` is a thin convenience wrapper for Harper resource write
+paths: it returns a ready-to-return `400 { error: "invalid_entities", invalid: [...] }`
+`Response` when validation fails, or `null` when the field is absent or every entry is valid.
+`WorkspaceState.ts`, `OrgEvent.ts`, and `Memory.ts` all call it early in `post()`/`put()`.
+
+## Where `entities` lives today
+
+Per the attention-plane spec's K&S-approved refinements, `entities: [String] @indexed` is an
+**additive, nullable** field on:
+
+- `WorkspaceState` (`schemas/workspace.graphql`)
+- `OrgEvent` (`schemas/event.graphql`)
+- `Memory` (`schemas/memory.graphql`) — added in v1 (not deferred to v2) for index-pushdown
+  uniformity across all three sources the future attention query joins.
+
+Existing rows on all three tables simply carry no `entities` — readers must tolerate absence,
+the same pattern already used for `Presence.activityUpdatedAt`. No migration, no backfill.
+
+`Relationship` gets **no** `entities` field: its `subject`/`object` columns already carry
+free-form entity-reference strings and are already indexed — they're the vocabulary carrier
+for that table. They are lowercased on write today but not yet validated against this
+vocabulary; wiring that validation is a follow-up, not part of this foundation slice.
+
+## What's explicitly NOT in this slice
+
+- The attention query (`AttentionQuery` / `flair attention <entity>`) that joins Memory,
+  Relationship, WorkspaceState, Presence, and OrgEvent by entity — shipped in flair#678
+  (`resources/AttentionQuery.ts`), a later slice.
+- Bootstrap collision surfacing ("others in the room") — shipped in flair#681
+  (`resources/collision-lib.ts` + `MemoryBootstrap.ts`'s "Others in the room" section), a
+  later slice.
+- Automatic entity extraction/tagging on write (producers set `entities` themselves today,
+  where they choose to; there's no NLP-derived auto-population yet).
+- Validating `Relationship.subject`/`object` against this vocabulary.
+
+These are tracked as follow-ups in `FLAIR-ATTENTION-PLANE.md`.

package/docs/federation.md

@@ -0,0 +1,179 @@
+# Federation
+
+Hub-and-spoke sync between Flair instances. A hub instance coordinates sync for one or more spoke instances.
+
+## Overview
+
+Federation lets multiple Flair instances share memories, relationships, and agent records. Each instance maintains its own Ed25519 identity. Sync requests are signed and verified against pinned peer public keys.
+
+```
+Spoke A ──[signed sync]──▶ Hub ◀──[signed sync]── Spoke B
+```
+
+- **Hub:** accepts sync pushes from paired spokes, can relay records between peers
+- **Spoke:** pushes local changes to the hub, receives changes from other spokes via the hub
+
+## Pairing a New Spoke (Bootstrap-User Flow)
+
+Pairing connects a spoke to a hub with mutual key pinning and an auth-aware handshake that works across all Harper topologies, including Harper Fabric.
+
+### Step-by-step
+
+**1. Hub admin generates a pairing token triple**
+
+On the hub machine, the admin runs `flair federation token`. The command emits a JSON triple containing a one-time bootstrap credential:
+
+```bash
+flair federation token --admin-pass <hub-admin-password>
+```
+
+Output (a single JSON object):
+
+```json
+{"token":"<one-time-pairing-token>","user":"<bootstrap-username>","password":"<bootstrap-password>","expiresAt":"<ISO-8601-timestamp>"}
+```
+
+Tokens expire after 60 minutes by default. Use `--ttl <minutes>` to adjust.
+
+**2. Hub admin shares the triple with the spoke admin**
+
+The JSON triple is shared out-of-band (secure file transfer, password manager, or similar). It must be stored as a plain JSON file on the spoke side or piped via stdin.
+
+**3. Spoke admin runs the pair command**
+
+On the spoke machine:
+
+```bash
+# From a file
+flair federation pair <hub-url> --token-from /path/to/triple.json
+
+# From stdin
+cat triple.json | flair federation pair <hub-url> --token-from -
+```
+
+**4. Behind the scenes**
+
+- The bootstrap user authenticates at the platform layer (works on standalone deployments and Harper Fabric alike).
+- The resource handler validates the pairing token, the signed request body, and the binding between the bootstrap user and the token.
+- On success the hub creates a `Peer` record for the spoke and removes the temporary bootstrap user. The spoke records the hub as its peer.
+
+After pairing, both instances pin each other's Ed25519 public keys and are ready to sync.
+
+## Why the Bootstrap-User Flow?
+
+Earlier designs relied on `allowCreate=true` combined with body-only authentication. That approach works on single-component deployments but breaks on Harper Fabric, where the platform authentication gate fires before the resource handler sees the request. The bootstrap-user flow (Option B) makes the pair handshake auth-aware so it operates correctly on all Harper topologies: standalone, Fabric single-node, and Fabric multi-node.
+
+## Fabric Pairing Example
+
+When the hub runs on Harper Fabric, adapt the hub URL to the Fabric pattern:
+
+```bash
+# 1. Hub admin generates the triple (on the Fabric host)
+ssh hub-host
+flair federation token --admin-pass <hub-admin-password> > /tmp/pair-triple.json
+
+# 2. Transfer the triple to the spoke admin (out-of-band)
+scp hub-host:/tmp/pair-triple.json ./pair-triple.json
+
+# 3. Spoke admin pairs using the Fabric URL
+flair federation pair https://<fabric-node>:19926/<instance-name> --token-from ./pair-triple.json
+```
+
+Replace `<fabric-node>`, `<instance-name>`, and `<hub-admin-password>` with your actual values.
+
+## Sync
+
+Push local changes to the hub:
+
+```bash
+flair federation sync --admin-pass <password>
+# Output: ✅ Synced 12 records (0 skipped) in 145ms
+```
+
+## Security
+
+### Signed requests
+
+Every federation request (pair, sync) is signed with the sender's Ed25519 private key. The receiver verifies the signature against the peer's pinned public key. Unsigned or tampered requests are rejected with 401.
+
+The signature covers the canonical JSON of the request body (keys sorted recursively, signature field excluded).
+
+### Encrypted key storage
+
+Private key seeds are stored in `~/.flair/keys/<instanceId>.key`, encrypted with AES-256-GCM. The encryption key is derived via HKDF from:
+
+1. `FLAIR_KEY_PASSPHRASE` environment variable (recommended for production), or
+2. An auto-generated random passphrase at `~/.flair/keys/.passphrase` (mode 0600)
+
+If neither the env var nor the passphrase file can be accessed, federation identity creation fails. Private keys are never stored in the database.
+
+### Pairing tokens
+
+New peers must present a valid, unexpired, unused pairing token. This prevents unauthorized instances from joining the federation. Tokens are generated by the hub admin and are single-use.
+
+Re-pairing an existing peer (same instance ID, same public key) does not require a token.
+
+### Originator enforcement
+
+Spoke instances can only push records they originated. A spoke cannot overwrite records from another spoke or from the hub. The hub can relay records from any origin.
+
+### Timestamp ceiling
+
+Records with `updatedAt` more than 5 minutes in the future are rejected. This prevents an attacker from using far-future timestamps to permanently win last-write-wins (LWW) merge conflicts.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `flair federation status` | Show instance identity and peer connections |
+| `flair federation pair <hub-url> --token-from <file>` | Pair this spoke with a hub using a token triple file (or `-` for stdin) |
+| `flair federation sync` | Push local changes to the hub (one-shot) |
+| `flair federation watch [--interval <s>]` | Run sync in a foreground daemon loop (default 30s) |
+| `flair federation reachability` | Probe local instance + each paired peer (read-only) |
+| `flair federation token [--ttl <min>]` | Generate a one-time pairing token triple (hub only) |
+
+## Conflict Resolution
+
+Federation uses record-level last-write-wins (LWW) with ISO timestamp comparison. When two instances modify the same record, the one with the later `updatedAt` wins. Field-level LWW is planned for a future version.
+
+## Troubleshooting
+
+### config.yaml port drift
+
+If the hub's configured port in `config.yaml` differs from the port the spoke is targeting, federation requests fail with a connection error. Verify the port matches between the spoke's pair URL and the hub's `config.yaml` (`federation.port` or the instance's listen port).
+
+```bash
+# On the hub, confirm the listening port
+grep -E 'port|federation' ~/.flair/config.yaml
+```
+
+### Local FederationInstance fetch needs auth
+
+When troubleshooting on the hub, fetching `/federation/instances/<id>` locally (e.g. via `curl localhost`) may return a 401 if the request does not carry the authentication headers the platform layer expects. On Fabric this gate is enforced even on localhost. Use the CLI tooling (`flair federation status`) instead of raw HTTP calls for local inspection.
+
+### `flair_pair_initiator` role not found on hub
+
+If pairing fails with a role-not-found error, the hub instance may be missing the `flair_pair_initiator` role. This role is created automatically during `flair init --remote` but can be lost if the database was reset or migrated manually. Re-run `flair init --remote` on the hub to restore default roles, then retry pairing.
+
+### Bootstrap user not deleted on Fabric
+
+After a successful pairing, the temporary bootstrap user is automatically deleted. If it persists on a Fabric deployment, check that the hub's Harper operations log does not show a rollback or permission error during the cleanup step. Manually removing the stale bootstrap user via the Harper Studio is safe if needed — it is never used after pairing completes.
+
+### Stale Peer record on spoke
+
+If a spoke was previously paired with a different hub (or the hub's identity key changed), the spoke may retain a stale `Peer` record pointing to the old hub. Remove the stale record before pairing with the new hub:
+
+```bash
+# Show current peers
+flair federation status
+
+# Remove a specific peer (replace <instanceId>)
+flair federation unpin <instanceId>
+```
+
+## Limitations (1.0)
+
+- **HTTP push only** — no persistent WebSocket connections or real-time sync
+- **Manual or watch-loop sync** — `flair federation sync` is one-shot; `flair federation watch --interval 30` runs it on a loop in a foreground daemon (wrap in launchd / systemd for production)
+- **Single hub** — spoke-to-spoke sync goes through the hub
+- **Record-level LWW** — not field-level; concurrent edits to different fields of the same record may lose data

package/docs/integrations.md

@@ -0,0 +1,197 @@
+# Flair integrations
+
+Where Flair already runs. Each integration shown here is a working surface — the same memory, federated across all of them, scoped per-agent by Ed25519 keys.
+
+> **The point.** Memory should follow the agent across orchestrators. Every entry below pulls from the same Flair instance, sees the same `agentId` namespace, respects the same isolation. Pick whichever harness you're shipping in; the memory layer doesn't care.
+
+---
+
+## Quick install matrix
+
+| Surface | Install path | Auth | Notes |
+|---------|--------------|------|-------|
+| **Claude Code** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Cursor** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Continue.dev** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **OpenAI Codex CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Gemini CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Goose** (block/goose) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Goose ships native MCP support |
+| **LangGraph (TS)** | [`langgraph-flair`](#langgraph-typescript) | FlairClient | Drop-in `BaseStore` |
+| **OpenClaw** | [`openclaw-flair`](#openclaw) | Ed25519 | Native plugin + context engine |
+| **n8n** | [`n8n-nodes-flair`](#n8n) | FlairApi credential | Three nodes (chat memory, search, store) |
+| **Hermes Agent** | [`hermes-flair`](#hermes-agent) | Ed25519 | Python `MemoryProvider` |
+| **Pi agent** | [`pi-flair`](#pi-agent) | Ed25519 | TS plugin |
+
+Don't see your harness? If it speaks **MCP** — Flair already works with `flair-mcp`. If it has a **custom memory protocol** like LangGraph's `BaseStore` or CrewAI's `RAGStorage`, an adapter is a ~200-line package; [open an issue](https://github.com/tpsdev-ai/flair/issues) or [send a PR](https://github.com/tpsdev-ai/flair).
+
+**Adjacent: memory bridges** — for moving memories between Flair and another memory product. Five bridges ship today (Mem0, ChatGPT exports, claude-project files, agentic-stack, markdown); see [bridges.md](bridges.md). Bridges are import/export plumbing, not live orchestrator integrations.
+
+---
+
+## Claude Code, Cursor, Codex, Gemini CLI, Continue.dev, Goose — via `flair-mcp`
+
+[`@tpsdev-ai/flair-mcp`](https://www.npmjs.com/package/@tpsdev-ai/flair-mcp) is a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes Flair as a memory tool to any MCP-speaking client. One server, every MCP client.
+
+No install step needed — every snippet below uses `npx -y @tpsdev-ai/flair-mcp`, which fetches and runs the server on demand (zero-install). The fastest path is `flair init`, which detects and wires these clients for you. To wire by hand, drop the relevant snippet into each tool's MCP config:
+
+**Claude Code** (`~/.config/claude-code/config.toml` or per-project `.claude/config.toml`):
+```toml
+[mcp.servers.flair]
+command = "npx"
+args = ["-y", "@tpsdev-ai/flair-mcp"]
+env = { FLAIR_AGENT_ID = "claude-code" }
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": { "FLAIR_AGENT_ID": "cursor" }
+    }
+  }
+}
+```
+
+**Codex CLI** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.flair]
+command = "npx"
+args = ["-y", "@tpsdev-ai/flair-mcp"]
+
+[mcp_servers.flair.env]
+FLAIR_AGENT_ID = "codex"
+```
+
+**Gemini CLI** (`~/.gemini/settings.json`): same shape as Cursor.
+
+**Continue.dev** (`~/.continue/config.json`):
+```json
+{
+  "experimental": {
+    "modelContextProtocolServer": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": { "FLAIR_AGENT_ID": "continue" }
+    }
+  }
+}
+```
+
+**Goose** (`~/.config/goose/profiles.yaml`):
+```yaml
+default:
+  extensions:
+    flair:
+      cmd: npx
+      args: ["-y", "@tpsdev-ai/flair-mcp"]
+      envs: { FLAIR_AGENT_ID: goose }
+```
+
+**Auth.** Set `FLAIR_AGENT_ID` to whatever identifier you want this client to claim. The MCP server will prompt you to register that agent on first call (`flair agent add <id>` writes the Ed25519 keypair). Subsequent calls auto-load the key.
+
+Full per-tool walkthrough including troubleshooting: [`docs/mcp-clients.md`](mcp-clients.md).
+
+---
+
+## LangGraph (TypeScript)
+
+[`@tpsdev-ai/langgraph-flair`](https://www.npmjs.com/package/@tpsdev-ai/langgraph-flair) implements LangGraph's `BaseStore`. Drop-in for `InMemoryStore`.
+
+```bash
+npm install @tpsdev-ai/langgraph-flair
+```
+
+```typescript
+import { FlairStore } from "@tpsdev-ai/langgraph-flair";
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+
+const store = new FlairStore({ agentId: "my-langgraph-agent" });
+const agent = createReactAgent({ llm, tools, store });
+```
+
+Maps LangGraph namespaces to Flair tags, keys to ids, values to JSON content. Search delegates to Flair's HNSW. Filter operators applied client-side. Full mapping table: [`packages/langgraph-flair/README.md`](../packages/langgraph-flair/README.md).
+
+LangGraph **Python** support is on the roadmap (same `BaseStore` shape, Python adapter).
+
+---
+
+## OpenClaw
+
+[`@tpsdev-ai/openclaw-flair`](https://www.npmjs.com/package/@tpsdev-ai/openclaw-flair) is the native OpenClaw plugin. Adds Flair as a memory provider AND registers the `flair` context engine that re-injects PERMANENT-tier rules (SOUL.md, IDENTITY.md, AGENTS.md) every turn.
+
+```bash
+openclaw plugins install @tpsdev-ai/openclaw-flair
+```
+
+Configuration via OpenClaw's standard plugin surface. See [`docs/openclaw.md`](openclaw.md) for the per-agent install pattern, including how to wire SOUL.md so behavioral anchors persist across long sessions without drift.
+
+---
+
+## n8n
+
+[`@tpsdev-ai/n8n-nodes-flair`](https://www.npmjs.com/package/@tpsdev-ai/n8n-nodes-flair) ships three nodes:
+
+- **FlairChatMemory** — drop-in chat-memory for n8n's AI Agent / LangChain workflow nodes. Same role as Postgres / Redis chat memory but with cross-orchestrator portability.
+- **FlairSearch** — semantic search over your Flair memories from any workflow.
+- **FlairApi** credential — Ed25519 keypair entry point for the agentId.
+
+Install via the standard n8n community-node UI (Settings → Community nodes → `@tpsdev-ai/n8n-nodes-flair`) or:
+
+```bash
+cd ~/.n8n && npm install @tpsdev-ai/n8n-nodes-flair
+```
+
+Walkthrough including a worked example flow: [`docs/n8n.md`](n8n.md).
+
+---
+
+## Hermes Agent
+
+[`hermes-flair`](https://github.com/tpsdev-ai/flair/tree/main/packages/hermes-flair) implements Nous Research [Hermes](https://github.com/NousResearch/hermes-agent)'s `MemoryProvider` plugin contract in Python. Bootstrap injection at session start, background prefetch between turns, two tools (`flair_search`, `flair_store`), built-in MEMORY.md mirroring, circuit breaker.
+
+```bash
+hermes plugins install path:/path/to/flair/packages/hermes-flair
+```
+
+Auth: TPS-Ed25519 (the same model the rest of Flair uses) — writes are isolated per agent identity server-side; reads are open within the org for non-private memories, with `visibility: private` staying owner-only. See [SECURITY.md](../SECURITY.md).
+
+---
+
+## Pi agent
+
+[`@tpsdev-ai/pi-flair`](https://www.npmjs.com/package/@tpsdev-ai/pi-flair) is the TS plugin for the [Pi coding agent](https://github.com/mariozechner/pi-coding-agent). Memory + identity for the Pi runtime.
+
+```bash
+npm install @tpsdev-ai/pi-flair
+```
+
+Pi resolves the plugin via its standard plugin config; pin `agentId` per host.
+
+---
+
+## Don't see your harness?
+
+If it speaks MCP, you're already covered — every MCP client works through `flair-mcp` (the section above lists 6 we've explicitly tested).
+
+If it has a custom memory protocol, the adapter pattern is small (~200 lines). LangGraph and Hermes are the reference implementations. **Adapters we'd love to see:**
+
+- LangGraph Python (mirror of our TS adapter)
+- CrewAI (Python `BaseRAGStorage` protocol)
+- AG2 / AutoGen (Python)
+- Mastra (TS, denser thread model)
+- ADK (Google, Python + TS)
+
+[Open an issue](https://github.com/tpsdev-ai/flair/issues) describing the harness and we'll triage. PRs welcome — see [`packages/langgraph-flair`](../packages/langgraph-flair) as the smallest-shape reference.
+
+---
+
+## See also
+
+- [Quickstart](quickstart.md) — `flair init` to working memory in 30 seconds
+- [Memory bridges](bridges.md) — import/export Flair ↔ Mem0, ChatGPT, claude-project, markdown, agentic-stack (five bridges shipped)
+- [Federation](federation.md) — pair instances peer-to-peer for cross-machine sync
+- [Supply-chain policy](supply-chain-policy.md) — what we do to keep this list of integrations safe
+- [The team](the-team.md) — the multi-agent rig that builds Flair, dogfooded on every harness above