@tpsdev-ai/flair 0.48.0 → 0.50.0

package/docs/mcp-clients.md

@@ -96,10 +96,10 @@ flair hook status                # wired? correct shape? which agent/instance?
 flair hook uninstall             # removes only Flair's hook entry
 ```
 
-`--harness claude-code` is the only supported value today (it's also the
-default) — the flag exists so a future harness is an additive registry entry,
-not a breaking change. `flair doctor` already checks for this same hook (see
-below) and recognizes anything `flair hook install` writes.
+`--harness` defaults to `claude-code`. `codex` is also supported (writes
+`~/.codex/hooks.json` — see the Codex section below). `flair doctor` checks
+the same hook for each detected harness and recognizes anything
+`flair hook install` writes.
 
 Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
 
@@ -111,7 +111,7 @@ Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y -p @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
+            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y -p @tpsdev-ai/flair-mcp@<version> flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
           }
         ]
       }
@@ -120,12 +120,23 @@ Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
 }
 ```
 
-Swap `me` for your `FLAIR_AGENT_ID`. Unlike the MCP-server snippets above, this
-one is shown **unpinned**, because that is what `flair hook install` writes and
-what the tooling recognises: `flair hook status` matches the exact unpinned
-command, so a hand-pinned hook reports `wired: false` there (while `flair
-doctor` still sees it). Pinning this line is therefore not yet supported —
-prefer `flair hook install`.
+Swap `me` for your `FLAIR_AGENT_ID` and `<version>` for `flair --version`. This
+is the same pin `flair init` writes into client MCP configs (`mcpServerSpec()`,
+flair#907): a wired hook should not self-update to a freshly published
+`flair-mcp` any more than a wired MCP client should. `flair hook install`,
+`flair init`, and `flair doctor --fix` (when adding a missing hook) write that
+pin; re-run `flair hook install` to advance a stale or pre-#1143 unpinned hook
+to the running CLI's version.
+
+That is a different surface from public plugin `mcp.json` files, which stay
+**unpinned** on purpose (flair#1308) so directory listings that scrape them do
+not freeze on a shipped version. User-local wiring is pinned; catalog
+manifests are not.
+
+`flair hook status` recognises both the current pinned `-p` form and an older
+unpinned `-p` invocation as `correctShape`. The pre-#1166 form (no `-p`, which
+runs the MCP shim) is still flagged. Prefer `flair hook install` over
+hand-editing.
 
 The `sh -c ... || true` wrapper is not decoration. The invocation resolves a
 package binary through whatever Node runtime your shell exposes, and under a
@@ -208,6 +219,46 @@ For project-scoped trust (per Codex's MCP guide), the same block in `.codex/conf
 
 Restart your Codex CLI session and the `flair_*` tools become available to the agent.
 
+#### Auto-recall on session start (optional hook)
+
+Wiring the MCP server alone does not load memory at session start — Codex
+then has pull tools it never thinks to call. The same `flair-session-start`
+command Claude Code uses writes Codex's SessionStart hook (same JSON schema,
+into `~/.codex/hooks.json`):
+
+```bash
+flair hook install --harness codex
+flair hook status --harness codex
+flair hook uninstall --harness codex
+```
+
+`flair doctor` reports this hook when Codex is detected. After install, trust
+the new command in Codex with `/hooks` — untrusted hooks are listed and
+skipped.
+
+---
+
+## Hookless harnesses (Gemini, Cursor, and anything without SessionStart)
+
+Some clients have no session-start hook Flair can write. Wiring the MCP
+server is necessary but not sufficient — the model still has to choose to
+call `bootstrap`. Add a short instruction block to the file that client
+already loads (`AGENTS.md`, `GEMINI.md`, or the equivalent):
+
+```markdown
+## Flair memory
+
+At the start of every session, call the Flair `bootstrap` tool before
+responding. Before a deep-dive, `memory_search` for related prior work.
+At wrap, `memory_store` durable lessons.
+```
+
+Without that, a config that looks wired is the known failure shape
+([#989](https://github.com/tpsdev-ai/flair/issues/989),
+[#908](https://github.com/tpsdev-ai/flair/issues/908)): tools exist, memory
+never enters the working set. Use `flair hook install` when the client has
+a SessionStart hook; use this static block when it does not.
+
 ---
 
 ## Step 3 — Verify
@@ -222,13 +273,13 @@ If you see (a) the agent calling the `bootstrap` tool returning soul + recent me
 
 ## What the MCP server exposes
 
-Eleven tools, kept deliberately small:
+Twelve tools, kept deliberately small:
 
 | Tool | What it does |
 |---|---|
 | `memory_search` | Semantic search across your agent's memories |
-| `memory_store` | Save a memory with type, durability, tags, visibility. Auto-dedups near-duplicates |
-| `memory_update` | Update an existing memory by ID — overwrite in place, or version it with `preserveHistory` |
+| `memory_store` | Save a memory with type, durability, tags, visibility. Auto-dedups near-duplicates. Optional `usedMemoryIds` cites memories that informed the write |
+| `memory_update` | Update an existing memory by ID — overwrite in place, or version it with `preserveHistory`. Optional `usedMemoryIds` for citation-on-write |
 | `memory_get` | Fetch a specific memory by ID |
 | `memory_delete` | Remove a memory |
 | `relationship_store` | Record a subject-predicate-object relationship triple (e.g. "nathan manages flair") |
@@ -237,6 +288,7 @@ Eleven tools, kept deliberately small:
 | `soul_get` | Get a soul entry |
 | `flair_workspace_set` | Set your agent's current workspace state (ref/branch, phase, task) in the Office Space |
 | `flair_orgevent` | Publish an org-wide coordination event (claim/release/status) to the Office Space |
+| `record_usage` | Report that recalled memories were actually used (id + optional one-line how-it-was-used). Drives `usageCount` / `usageBoost` |
 
 Writes are scoped per-agent (your `FLAIR_AGENT_ID`) and enforced by Flair's server, not by client convention — you can't write as another agent. Reads are more open by design: any agent on the same Flair instance can read any other agent's **non-private** memories, with no grant to set up (open-within-org read; see [SECURITY.md](../SECURITY.md)).
 
@@ -266,6 +318,24 @@ The MCP server has no client-side flags beyond these env vars; everything else (
 
 ---
 
+## What about pi?
+
+pi has no MCP client support, so Flair ships a **native pi extension** instead: [`@tpsdev-ai/pi-flair`](../packages/pi-flair/README.md). Same backend, same agent isolation, zero MCP in the path.
+
+Wiring is a `packages` entry in pi's own settings (`~/.pi/agent/settings.json`), not an `mcpServers` block:
+
+```json
+{
+  "packages": ["npm:@tpsdev-ai/pi-flair@<version>"]
+}
+```
+
+`flair init --client pi` writes exactly that (pinned), or use pi's own installer: `pi install npm:@tpsdev-ai/pi-flair`. `flair doctor` detects pi and checks the wiring — including the one known trap: **an `npm:` spec under the `extensions` settings key is silently ignored by pi** (`extensions` takes local file paths only; package sources belong under `packages` — [#1346](https://github.com/tpsdev-ai/flair/issues/1346)). Doctor calls that misconfiguration out by name, and `flair doctor --fix` moves the entry.
+
+One difference from the MCP clients above: pi settings carry no per-package `env` block, so `FLAIR_AGENT_ID` (and `FLAIR_URL` when non-default) must be exported in the environment that launches pi. Doctor reports what it sees in its own shell and says so — it cannot observe the environment of every pi launch.
+
+---
+
 ## What about Hermes (Nous Research)?
 
 Hermes uses its own Python-native `MemoryProvider` ABC instead of MCP. It has its own Flair integration in [`packages/hermes-flair/`](../packages/hermes-flair). Same backend, same agent isolation, different plug shape.
@@ -280,7 +350,7 @@ Future MCP-capable agent CLIs (and there are more landing every month) will work
 
 **"connection_error: could not reach Flair at http://127.0.0.1:19926".** The Flair server isn't running. Run `flair status` to check; `flair start` to bring it up.
 
-**"auth_error: …" on every call.** The agent identity doesn't match a registered key. Re-run `flair agent add <id>` (idempotent on re-add — won't lose existing memories).
+**"auth_error: …" on every call.** The agent identity doesn't match a registered key. Re-run `flair agent add <id>` (idempotent on re-add — won't lose existing memories). Against a hosted instance the same three shapes apply (record missing / key mismatch / config wrong), and a by-id 404 is fail-closed ownership, not an existence signal — [Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
 
 **Tool calls succeed but the agent doesn't see results in subsequent turns.** Check that the CLI is actually invoking `bootstrap` at session start — most CLIs need an explicit prompt nudge ("call the bootstrap tool now") on first use. Subsequent turns should pick up automatically once the CLI sees the schema.
 

package/docs/notes/mcp-oauth-model2.md

@@ -61,25 +61,43 @@ opt-in, never something the server infers. The practical consequences:
   agent id to attach the sub to it; the step's output states the resulting
   `sub → Agent` mapping in as many words.
 - **Linking a sub to an existing Agent (the same-identity opt-in).** Re-run
-  `flair mcp enable` with the SAME `--idp-provider`/`--idp-subject` and
-  `--principal <your-cli-agent-id>`. The existing `(provider, subject)`
-  Credential is RE-POINTED to that principal — one Credential row per subject,
-  so resolution stays deterministic. The link *replaces* the mapping; it does
-  not merge the two agents' memories.
+  `flair mcp enable` with the SAME `--idp-subject` and `--principal
+  <your-cli-agent-id>`. The existing Credential for that subject is RE-POINTED
+  to that principal — one ACTIVE Credential row per subject, so resolution stays
+  deterministic. The link *replaces* the mapping; it does not merge the two
+  agents' memories.
 - **First diagnostic: ask the server who you are.** The `bootstrap` tool's
   response always carries the resolved `agentId` and a `scope` descriptor
   (`scope.agentId` / `scope.isAdmin` / `scope.reads`, flair#1182). "My memory
   is empty over the connector" + a `bootstrap.agentId` you don't recognize =
   the sub resolved to a different (often JIT-provisioned) Agent — link it as
   above.
-- **JIT caveat.** A JIT-provisioned mapping (`FLAIR_MCP_JIT_PROVISION=1`)
-  stamps `idpProvider: "mcp-oauth"`. Runtime resolution matches on
-  `(kind, idpSubject)` only, but the *linking* upsert matches on
-  `(kind, idpProvider, idpSubject)` — so when re-linking a JIT-provisioned
-  sub, pass `--idp-provider mcp-oauth` (matching the JIT stamp), or first
-  revoke the JIT credential (`status: "revoked"`). Linking under a different
-  provider name creates a SECOND active credential for the same subject, and
-  which one wins resolution is unspecified.
+- **Re-linking under a different provider name SUPERSEDES (flair#1317).** A
+  JIT-provisioned mapping (`FLAIR_MCP_JIT_PROVISION=1`) stamps `idpProvider:
+  "mcp-oauth"`, so re-linking that sub as, say, `github` is a *provider change*.
+  The invariant is **at most one ACTIVE `Credential(kind:"idp", idpSubject)` per
+  subject, regardless of provider** — the same key runtime resolution uses. So
+  the link revokes the prior credential (terminal `status: "revoked"`, the row
+  retained for audit) and writes the new one, in a single batched write. You do
+  NOT need to match `--idp-provider` to the JIT stamp, and you do not need to
+  revoke anything by hand first. `provisionIdpIdentityMapping` returns
+  `credentialSuperseded: true` with the revoked ids, and the `flair mcp enable`
+  identity-mapping step prints them.
+
+  Read `credentialSuperseded` as **"the prior credential for this subject is now
+  dead"**, not "a duplicate was tidied up". `idpProvider` is audit/diagnostic
+  metadata on the row; it does not namespace the subject. Residual risk, ruled
+  acceptable (Sherlock, #1317): anyone who can run the link for a subject can
+  revoke that subject's existing credential, so two genuinely different people
+  sharing one subject string across providers would evict each other. IdP
+  subjects are opaque per-IdP identifiers, so this is remote — and the
+  alternative, duplicate active credentials resolved by iteration order, is
+  strictly worse.
+
+  Before the fix, the linking upsert deduped on `(kind, idpProvider,
+  idpSubject)` while resolution read `(kind, idpSubject)`, so a cross-provider
+  re-link silently created a SECOND active credential and which one won was
+  unspecified.
 
 The two-identity contract (a distinct connector agent sees other agents'
 org-non-private rows, never their private rows, 404-never-403 by id; a linked

package/docs/quickstart-fabric.md

@@ -119,7 +119,7 @@ Same connector, different panel. This is the field-verified sequence — includi
 
    Keep the pass file mode `0600`. Newer releases add `--admin-pass-file <path>`, which reads the file in-process (invisible to `ps`) — check `flair agent add --help` and prefer it when present.
 
-5. **Restart the MCP process** if it started before the key existed — it does not pick the key up mid-session. Still 401 with the key on disk? Set the key path explicitly in the agent's MCP env: `FLAIR_KEY_PATH=~/.flair/keys/grok-cos.key`. Known papercut, tracked in [flair#1271](https://github.com/tpsdev-ai/flair/issues/1271).
+5. The next tool call picks up the key — a miss is not cached. A 401 names the agent and the paths that were looked in. If those are not where `flair agent add` wrote the file, the MCP process's home differs from the shell; set `FLAIR_KEY_PATH` to the absolute path of the `.key` file.
 
 6. Verify: ask the agent to "load my Flair bootstrap". You should get soul + memories **including shared org context** — findings written by teammate agents. A shared-visibility write from this agent is now readable by every org agent.
 

package/docs/quickstart.md

@@ -164,6 +164,14 @@ Add `--explain` to see the ranking inputs per hit — the raw score, the composi
 
 ## 6. Give your agent context on boot
 
+With MCP wired (`flair init` does this for every client it detects), the recommended session-start is the `bootstrap` tool. In Claude Code that appears as `mcp__flair__bootstrap` (Claude Code's namespaced name for the server's `bootstrap` tool). Add this to your `CLAUDE.md`:
+
+```
+At the start of every session, run mcp__flair__bootstrap before responding.
+```
+
+Use the CLI variant — `flair bootstrap --agent <id>` — when MCP is not wired: previewing context yourself, a script, or any agent that can run a shell command.
+
 ```bash
 flair bootstrap --agent local --max-tokens 2000
 ```
@@ -174,15 +182,7 @@ flair bootstrap --agent local --max-tokens 2000
 ✓ budget 20/2000 tokens (1%) · ✓ 1 included · ✓ 0 truncated
 ```
 
-Soul entries and relevant memories, in one block sized to a token budget. Paste it into any LLM session — Claude Code, Codex, Cursor, an API call — to hand the agent its identity and memory in one shot.
-
-Using Claude Code? Add this to your `CLAUDE.md`:
-
-```
-At the start of every session, run mcp__flair__bootstrap before responding.
-```
-
-With the MCP server wired up — `flair init` does this automatically for every client it detects — Claude Code runs bootstrap on every new session. See the [integration section in README.md](../README.md#integration).
+Soul entries and relevant memories, in one block sized to a token budget. Paste that CLI output into any LLM session that does not have the MCP server — Codex, Cursor, an API call — to hand the agent its identity and memory in one shot. See the [integration section in README.md](../README.md#integration).
 
 ## What's next
 

package/docs/standalone-local.md

@@ -107,6 +107,9 @@ logging:
 | `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. After first start, the persisted user record is the source of truth. | Set at install time. See [secrets-and-keys.md](secrets-and-keys.md) for rotation. |
 | `FLAIR_KEY_PASSPHRASE` | Passphrase for AES-256-GCM encryption of federation private-key seeds. | Set explicitly for production federation deployments. |
 | `FLAIR_URL` | Override the Flair base URL for CLI commands (points to a remote instance). | When connecting from a different machine. |
+| `FLAIR_EMBED_THREADS` | CPU threads for in-process embedding. Default is `max(1, availableParallelism() − 1)` — host-aware, one core left for Harper. | Pin a positive integer on a dedicated ingest host, or when the default leaves cores idle / oversubscribed. See [deployment.md](deployment.md#performance-related-environment-variables). |
+| `FLAIR_HYBRID_RETRIEVAL` | Hybrid BM25 + vector retrieval (default on). | Set `false` to revert to HNSW-only. |
+| `FLAIR_MODELS_DIR` | Directory the embedding GGUF is loaded from. | When the model lives outside `<data-dir>/models`. |
 
 ---
 

package/docs/troubleshooting.md

@@ -105,6 +105,31 @@ date
 
 If using the MCP server, restart Claude Code after rotating keys.
 
+`flair agent list` is localhost-only. Against a hosted instance, the
+discriminator is the 401 body on a signed request (`unknown_agent` vs
+`invalid_signature`), not a local agent list. Adapter-shaped walkthrough:
+[integrations.md — Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
+
+### 404 on `GET`/`PUT /Memory/{id}`
+
+**Symptoms:** `memory_get`, a by-id update, or an adapter write/read against
+`/Memory/{id}` returns 404. The agent reports "not found" or "Harper rejected
+the verb."
+
+**This is not an existence signal.** By-id routes return the same 404 when
+the id is absent and when the record exists but the caller may not see it
+(fail-closed ownership, [flair#1264](https://github.com/tpsdev-ai/flair/issues/1264)).
+A 403 would confirm the id and can name the owner; Flair refuses that.
+
+**Also not this:** `401 unknown_agent` / `401 invalid_signature` (identity —
+see above). Harper's catch-all 404 when the Flair app is not loaded yet
+(`/Health` can already be 200). A `FLAIR_URL` with a path prefix.
+
+Creates go to `POST /Memory/` (id in the body). Do not treat a by-id 404 as
+a reason to paste admin credentials into the agent's environment.
+
+Full adapter guide: [integrations.md — Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
+
 ### "signing key ... could not be parsed as an Ed25519 private key"
 
 **Symptoms:** `flair doctor` reports, naming the file:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "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",
@@ -59,7 +59,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.18.0 || >=24.0.0"
   },
   "dependencies": {
     "@harperfast/oauth": "2.5.0",
@@ -83,7 +83,8 @@
     "@opentelemetry/core": "^2.8.0",
     "uuid": "^11.1.1",
     "tar": "^7.5.22",
-    "@tootallnate/once": "^2.0.1"
+    "@tootallnate/once": "^2.0.1",
+    "form-data": "^4.0.6"
   },
   "devDependencies": {
     "@playwright/test": "1.59.1",