@tpsdev-ai/flair 0.32.0 → 0.33.0

package/README.md

@@ -6,55 +6,11 @@
 
 > **The identity and memory substrate for AI agents. Crypto-pinned. Federated. Self-hosted.**
 
-Every agent framework gives you chat history. None give you *identity*. Flair gives an agent three things that survive a restart and follow it between orchestrators:
-
-- **Identity** — an Ed25519 keypair. The agent signs every request. No shared secrets.
-- **Memory** — persistent knowledge with semantic search, embedded in-process. No API calls.
-- **Soul** — the personality, values and procedures that make it *that* agent.
-
-Self-hosted on [Harper](https://harper.fast) as a single process. No sidecars, no vector database, no embedding API.
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│  same agent, same memory, every harness                          │
-│                                                                  │
-│  Claude Code  ─┐                                                 │
-│  Cursor       ─┤                                                 │
-│  Codex CLI    ─┼─[ flair-mcp ]─┐                                 │
-│  Gemini CLI   ─┤               │                                 │
-│  Continue.dev ─┤               │   ┌──────────────────────┐      │
-│  Goose        ─┘               ├─▶ │  Flair (self-hosted) │      │
-│  LangGraph   ─[ langgraph-flair ]──│  Ed25519 / HNSW /    │      │
-│  OpenClaw    ─[ openclaw-flair  ]──│  Soul + Memory       │      │
-│  n8n         ─[ n8n-nodes-flair ]──└──────────┬───────────┘      │
-│  Hermes      ─[ hermes-flair    ]─┘           │ federation       │
-│  Pi agent    ─[ pi-flair        ]─┘           │ (hub/spoke)      │
-│                                               ▼                  │
-│                                    ┌──────────────────────┐      │
-│                                    │  Flair (Fabric hub)  │      │
-│                                    └──────────────────────┘      │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-11 harness surfaces today. Pick whichever you're shipping in; the memory layer doesn't care. **[Full integrations catalog →](docs/integrations.md)**
+Every agent framework gives you chat history. None give you *identity*. Flair gives an agent three things that survive a restart and follow it between orchestrators: an **identity** it proves with an Ed25519 keypair, **memory** it searches by meaning rather than by keyword, and a **soul** — the personality, values and procedures that make it *that* agent.
 
 ## Quick start
 
-Two front doors. Pick by where your code already runs.
-
-### Already on Harper? Load Flair as a component
-
-Flair *is* a Harper component. Deploy it into the instance your application already runs in and call its resources directly — `await h.post({ agentId, content })` is a **method call**, not a network call. No second service to operate, no HTTP round trip, and no key to distribute: a caller in the same process is already inside the trust boundary and names the agent it is acting as, per call.
-
-Adding it takes nothing away. The HTTP surface keeps serving MCP clients and remote agents exactly as before.
-
-**→ [Embedding Flair in a Harper app](docs/embedding-in-a-harper-app.md)** — the whole in-process contract, measured against a real instance: resolving the resource, the table-vs-resource distinction that decides whether your memories are scoped at all, N agents in one process, and registering agents with no shell on the node.
-
-### Everywhere else — install the CLI
-
-A laptop, a VPS, an MCP client, or any language over HTTP. Needs **Node.js 22+** and a **user-writable npm global prefix**.
-
-> ⚠️ **Never `sudo npm install -g @tpsdev-ai/flair`.** A root-owned install can't write the embedding model into its own package directory, so semantic search silently degrades to keyword-only. `flair init` and `flair doctor` will warn you loudly. Use `nvm`, or point npm at your home directory: `npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`.
+Runs on a laptop, a VPS, or anywhere Node does. Needs **Node.js 22+**.
 
 ```bash
 # 1. Install the CLI (no sudo)
@@ -79,19 +35,30 @@ Step 4 finds the memory you never keyword-matched:
 
 That trailing figure is a rank score, normalized so the top hit is always near 100% — ordering, not confidence.
 
-`flair init` installs and starts Harper, creates the agent's Ed25519 keypair, verifies semantic search actually works, wires every MCP client it detects (Claude Code, Cursor, Codex CLI, Gemini CLI) to `npx -y @tpsdev-ai/flair-mcp`, and runs a smoke test. Restart your MCP client afterwards, then ask the agent *"what do you remember about me?"*
+`flair init` installs and starts Harper, creates the agent's Ed25519 keypair, verifies semantic search actually works, wires every MCP client it detects (Claude Code, Cursor, Codex CLI, Gemini CLI), and runs a smoke test. Restart your MCP client afterwards, then ask the agent *"what do you remember about me?"*
 
 > **Pass `--agent`.** A bare `flair init` bootstraps the instance and stops there — no agent, no keypair, no MCP wiring.
 
 Full walkthrough with expected output at every step: **[docs/quickstart.md](docs/quickstart.md)**.
 
+### One install, one binary
+
+`npm install -g @tpsdev-ai/flair` puts a single command on your `PATH`: `flair`. That is the whole install, and it needs a **user-writable npm global prefix** — which is why step 1 says *no sudo*. A root-owned install can't write the embedding model into its own package directory, so semantic search silently degrades to keyword-only. Use `nvm`, or point npm at your home directory — `npm config set prefix ~/.npm-global`, then add `~/.npm-global/bin` to `PATH`. `flair init` and `flair doctor` both check for this and say so loudly.
+
+Two different things get called "MCP" here, and you get them differently:
+
+- **The server has an MCP surface built in.** `/mcp` is a JSON-RPC endpoint exposing 12 curated tools, guarded by OAuth bearer tokens. It ships inside the package — and it is **off by default**: until you set `FLAIR_MCP_OAUTH` *and* a public issuer (`FLAIR_MCP_ISSUER`, falling back to `FLAIR_PUBLIC_URL`), no `/mcp` route is registered and the path returns 404. No documented client setup uses it today.
+- **What your MCP client actually talks to is a separate package** — `@tpsdev-ai/flair-mcp`, a stdio adapter — and that one is deliberately not installed globally. `flair init` writes `npx -y @tpsdev-ai/flair-mcp@<version>` into each client's config, pinned to the CLI's own version, so the client fetches it on demand and there is no second global package to keep in step.
+
+`@tpsdev-ai/flair-client` is likewise its own package: add it to a project when you want to call Flair from your own code ([JavaScript / TypeScript](#javascript--typescript)).
+
 ### Where the agent's key lives
 
 `flair init --agent mybot` writes the private key to `~/.flair/keys/mybot.key` (mode `0600`) and the public half beside it as `mybot.pub`. Only the **public** key is registered on the instance; the private key never leaves the machine. `--keys-dir` writes both somewhere else.
 
 **Back that file up — it is the agent's identity, and there is one copy.** Memories are not encrypted with it, so losing it costs the identity, not the data: the agent can no longer sign, and every HTTP call it makes fails. Recovery is `flair agent rotate-key mybot`, which mints a new pair and re-registers the public half — it needs the admin password `flair init` wrote to `~/.flair/admin-pass`, so back that up too. Otherwise treat the key like an SSH key: one per agent per host, never copied between machines ([docs/secrets-and-keys.md](docs/secrets-and-keys.md)).
 
-**The in-process path needs no key at all.** Keys are how an agent *outside* the process proves who it is. Code running inside the same Harper instance asserts identity through the call context instead — `agentContext("mybot")` — which Flair reads and acts on with no signature, no `Agent`-table lookup and no registration. That is deliberate: same-process code could write the storage tables directly, so demanding a signature from it would be theatre. It is also why that id must come from your own server-side state and never from request data.
+Keys are how an agent *outside* the process proves who it is. Code running inside the same Harper instance needs no key at all — see [Embedded in a Harper app](#embedded-in-a-harper-app-in-process).
 
 ### Useful flags
 
@@ -138,9 +105,35 @@ Write a memory, then find it by meaning. The same memory is visible to every har
 
 One Ed25519 identity, one memory store, three MCP-capable CLIs. A memory written from Claude Code is retrievable from Codex CLI and Gemini CLI a moment later. Identity and history aren't bound to one orchestrator's runtime.
 
+## One agent, every harness
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  same agent, same memory, every harness                          │
+│                                                                  │
+│  Claude Code  ─┐                                                 │
+│  Cursor       ─┤                                                 │
+│  Codex CLI    ─┼─[ flair-mcp ]─┐                                 │
+│  Gemini CLI   ─┤               │                                 │
+│  Continue.dev ─┤               │   ┌──────────────────────┐      │
+│  Goose        ─┘               ├─▶ │  Flair (self-hosted) │      │
+│  LangGraph   ─[ langgraph-flair ]──│  Ed25519 / HNSW /    │      │
+│  OpenClaw    ─[ openclaw-flair  ]──│  Soul + Memory       │      │
+│  n8n         ─[ n8n-nodes-flair ]──└──────────┬───────────┘      │
+│  Hermes      ─[ hermes-flair    ]─┘           │ federation       │
+│  Pi agent    ─[ pi-flair        ]─┘           │ (hub/spoke)      │
+│                                               ▼                  │
+│                                    ┌──────────────────────┐      │
+│                                    │  Flair (Fabric hub)  │      │
+│                                    └──────────────────────┘      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+11 harness surfaces today. Pick whichever you're shipping in; the memory layer doesn't care. **[Full integrations catalog →](docs/integrations.md)**
+
 ## How it works
 
-Flair is a native [Harper v5](https://harper.fast) application. Harper handles HTTP, persistence (RocksDB), and application logic in one process.
+Flair is a native [Harper v5](https://harper.fast) application. Harper handles HTTP, persistence (RocksDB), and application logic in one process — self-hosted, with no sidecars, no vector database and no embedding API.
 
 ```
 Agent ──[Ed25519-signed request]──▶ Flair (Harper)
@@ -178,24 +171,22 @@ See **[DESIGN.md](DESIGN.md)** for the invariants behind the three primitives
 | **Web admin** | Server-rendered UI for principals, connectors, IdPs and instance config. No separate dashboard service. |
 | **Benchmarks** | [`flair-bench`](packages/flair-bench/README.md) scores candidate embedding models against the same recall corpus Flair's CI gates on. Runs standalone — no Flair install, no server. |
 
-Trust-graded recall reaches the authenticated HTTP API and the native `/mcp` tools today; CLI, `@tpsdev-ai/flair-client` and `flair-mcp` exposure is a follow-up. REM needs a configured generative backend (Ollama, OpenAI, Anthropic, …) — without one, `flair rem rapid` fails with `Reflection error: No generative backend configured`.
+Trust-graded recall reaches the authenticated HTTP API and the built-in `/mcp` tools today — the latter being off by default, see [One install, one binary](#one-install-one-binary). CLI, `@tpsdev-ai/flair-client` and `flair-mcp` exposure is a follow-up. REM needs a configured generative backend (Ollama, OpenAI, Anthropic, …) — without one, `flair rem rapid` fails with `Reflection error: No generative backend configured`.
 
 ## How Flair compares
 
-| | Flair | Mem0 | Honcho | Letta (MemGPT) | Built-ins (OAI/Anthropic/Google) |
-|---|---|---|---|---|---|
-| **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 |
-| **Soul / persistent character** | **first-class** | optional | persona-shaped | optional | no |
-
-Parity rows are omitted: Mem0, Honcho and Letta are all open-source, self-hostable, and do semantic search. Those are table stakes here.
+Every product here does semantic recall over stored memories. These are the dimensions they actually differ on.
 
-The honest gaps — if you need one of these specifically, use that tool:
+| | Flair | Mem0 | Honcho | Letta (MemGPT) | [SageOx](https://sageox.ai) | Built-ins (OAI/Anthropic/Google) |
+|---|---|---|---|---|---|---|
+| **Where memories live** | infrastructure you run | self-host or Mem0 Cloud | self-host or hosted API | self-host or Letta Cloud | SageOx cloud | vendor cloud |
+| **Memory is scoped to** | the agent, via an Ed25519 keypair | tenant / user | per-user tenant | the runtime | the team | the account |
+| **Reaches other orchestrators** | 11 harnesses, incl. workflow and agent frameworks | several | several | Letta's runtime | 14+ coding agents and editors, via hooks, plugins and instruction files | no |
+| **Sync between instances you run** | hub/spoke federation | no | no | no | one hosted service | one hosted service |
+| **Captures in-person conversation** | no | no | no | no | yes — Ox Dot | no |
+| **Per-agent persistent character** | first-class (Soul) | optional | persona-shaped | optional | team context, not per-agent | no |
 
-- Mem0's **cloud sync UX** is more polished, if you're happy with their hosting.
-- Honcho's **persona model** is more developed, if rich personality modeling is the priority.
-- Letta's **runtime integration** is tighter, if you're building on their agent loop.
+**Where Flair loses.** [SageOx's Ox Dot](https://sageox.ai) records in-person meetings, standups and whiteboard sessions and pipes them into shared context; Flair has no ambient capture of anything that isn't already text in a tool. Mem0's hosted sync is more polished. Honcho's persona model is more developed. Letta's integration with its own agent loop is tighter than anything Flair offers. And there is no Flair-operated cloud — running it is your job.
 
 ## Integration
 
@@ -298,7 +289,11 @@ Sign `agentId:timestamp:nonce:METHOD:/path` with the agent's private key. Protoc
 
 ### Embedded in a Harper app (in-process)
 
-Flair *is* a Harper component. If your application already runs on Harper, load Flair into the same instance and call its resources directly — a method call instead of an HTTP round trip, and no key anywhere.
+The second front door, and the one to take if your code already runs on Harper.
+
+Flair *is* a Harper component. Deploy it into the instance your application already runs in and call its resources directly — `await h.post({ agentId, content })` is a **method call**, not a network call. No second service to operate, no HTTP round trip, and no key to distribute: a caller in the same process is already inside the trust boundary and names the agent it is acting as, per call.
+
+Adding it takes nothing away. The HTTP surface keeps serving MCP clients and remote agents exactly as before.
 
 ```javascript
 import { server } from "harper";
@@ -312,7 +307,11 @@ const h = await collectionResource(Memory, agentContext("mybot"));
 await h.post({ agentId: "mybot", content: "...", durability: "standard" });
 ```
 
-`databases.flair.Memory` is the **table** (raw storage); the exported `Memory` class is the **resource**, where auth, read-scoping, visibility and embedding live. `new Memory(...)` is not a substitute for `collectionResource` — a create needs a collection-bound instance only Harper can produce. Both helpers refuse a missing agent id rather than defaulting it, because a resource invoked with no context resolves to Flair's trusted `internal` verdict and runs unfiltered across every agent. Full guide: **[docs/embedding-in-a-harper-app.md](docs/embedding-in-a-harper-app.md)**.
+`databases.flair.Memory` is the **table** (raw storage); the exported `Memory` class is the **resource**, where auth, read-scoping, visibility and embedding live. `new Memory(...)` is not a substitute for `collectionResource` — a create needs a collection-bound instance only Harper can produce. Both helpers refuse a missing agent id rather than defaulting it, because a resource invoked with no context resolves to Flair's trusted `internal` verdict and runs unfiltered across every agent.
+
+**This path needs no key at all.** Keys are how an agent *outside* the process proves who it is. Code running inside the same Harper instance asserts identity through the call context instead — `agentContext("mybot")` — which Flair reads and acts on with no signature, no `Agent`-table lookup and no registration. That is deliberate: same-process code could write the storage tables directly, so demanding a signature from it would be theatre. It is also why that id must come from your own server-side state and never from request data.
+
+**→ [Embedding Flair in a Harper app](docs/embedding-in-a-harper-app.md)** — the whole in-process contract, measured against a real instance: resolving the resource, the table-vs-resource distinction that decides whether your memories are scoped at all, N agents in one process, and registering agents with no shell on the node.
 
 ### Auth across surfaces
 
@@ -357,6 +356,7 @@ Full model, threat analysis and recommendations in [SECURITY.md](SECURITY.md).
 - Ed25519 cryptographic identity — agents sign every request.
 - Writes are always agent-scoped. An agent can only write its own records.
 - Reads are open within the org: any agent can read any other agent's non-private memory, no grant required. `private` is the one owner-only exception ([DESIGN.md](DESIGN.md#access-model-open-within-the-org-closed-at-the-federation-edge)).
+- Which memories are non-private is decided at write time, from durability: `permanent`/`persistent` default to `shared`, `standard`/`ephemeral` to `private`. A write that names neither is `standard`, so it lands `private`. Say what you mean with `--visibility shared|private` (CLI) or `visibility` (MCP / SDK); a write response names the visibility the record landed on, so it never has to be inferred.
 - The admin password is generated by `flair init` and written to `~/.flair/admin-pass` (mode 0600). The CLI prints the path, never the value. Prefer `--admin-pass-file` over `--admin-pass` so it stays out of `ps` and shell history.
 - Key rotation via `flair agent rotate-key`.
 

package/SECURITY.md

@@ -69,6 +69,13 @@ centralized read-scope rule), not application logic:
 **Private memories are strictly owner-only** — a memory written with
 `visibility: private` is returned only to its author, never to another agent.
 
+**A write that does not name a visibility gets one anyway.** The server derives
+it from the memory's durability: `permanent`/`persistent` → `shared`,
+`standard`/`ephemeral` → `private`. Durability itself defaults to `standard`,
+so a write naming neither is stamped `private` and is owner-only. An explicit
+`visibility` on the write always overrides the rule, and the response to a
+create names the value the record actually landed on.
+
 ### Cross-Agent Access (within an org)
 
 Within an org, an agent reads every non-private memory directly — no grant

package/config.yaml

@@ -6,6 +6,40 @@ rest: true
 # http:
 #   port: 19926
 
+# Harper does not read a component's `.env` implicitly — it only loads env
+# files a component ASKS for, via this plugin. Without this block a `.env`
+# sitting next to config.yaml is inert: the file is present and its values
+# never reach `process.env`. That is exactly what a deployed instance hit —
+# `FLAIR_PUBLIC_URL` was set in the deployed component's `.env` and OAuth
+# discovery kept advertising a loopback issuer (flair#1005, #1000).
+#
+# MUST STAY FIRST. Config keys are iterated in file order by Harper's
+# component loader, and each plugin's initial entry load is awaited before
+# the next key is processed — so declaring this above `jsResource` is what
+# guarantees `process.env` is populated before `dist/resources/*.js` are
+# imported. Most consumers read `process.env` per request and would not care
+# (resources/OAuth.ts, resources/AdminInstance.ts, resources/XAA.ts,
+# resources/a2a-url.ts), but `resources/mcp-oauth.ts` decides at MODULE LOAD
+# whether to mount `/mcp`; move this below `jsResource` and that decision is
+# made against an env that has not been loaded yet.
+#
+# No `.env` is required, which is the case for essentially every local
+# install: when the glob matches nothing the plugin never fires and emits
+# nothing. Measured — a boot log with this block and no `.env` differs from
+# one without the block only in the PID and in non-deterministic table-init
+# ordering. (A MALFORMED declaration is loud, not silent: a pattern
+# containing '..' produced both an `Ignoring invalid loadEnv files pattern`
+# warning and a `Could not load component 'loadEnv'` error, which is the
+# positive control for that silence.)
+#
+# Application variables only. Harper composes its OWN configuration before
+# component `.env` files load, so Harper-level settings cannot be set this
+# way; `HARPER_CONFIG` / `HARPER_DEFAULT_CONFIG` / `HARPER_SET_CONFIG` are
+# refused at the injection point and warned about (harper#1513). Those
+# belong in the process environment or harper-config.yaml.
+loadEnv:
+  files: '.env'
+
 graphqlSchema:
   files: schemas/*.graphql
 

package/dist/cli.js

@@ -9684,17 +9684,38 @@ program
     // PID — see parseListeningPids (flair#800/flair#905): this used to SIGTERM
     // every process holding ANY socket on the port, so `flair stop` could kill
     // itself (leaving Flair running) or kill an unrelated client of it.
+    //
+    // Attribution guard (flair#915): the port is not an identity. Refuse to
+    // SIGTERM a PID that cannot be attributed to this instance.
     try {
         const { execSync } = await import("node:child_process");
         const pids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
         if (pids.length > 0) {
-            for (const pid of pids) {
-                try {
-                    process.kill(pid, "SIGTERM");
+            const dataDir = defaultDataDir();
+            const harperPid = readHarperPid(dataDir);
+            if (harperPid !== null && !pids.includes(harperPid)) {
+                console.error(`⚠️  Process(es) on port ${port} (PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")}) `
+                    + `do not match this Flair instance (PID ${harperPid}). `
+                    + `Not stopping — cannot attribute the process to this instance. `
+                    + `Stop the process manually if it is not Flair.`);
+                process.exit(1);
+            }
+            else if (harperPid === null) {
+                console.error(`⚠️  Process(es) on port ${port} (PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")}) `
+                    + `but no PID file in data directory — not a running Flair instance. `
+                    + `Not stopping — cannot attribute the process to this instance. `
+                    + `Stop the process manually if it is not Flair.`);
+                process.exit(1);
+            }
+            else {
+                for (const pid of pids) {
+                    try {
+                        process.kill(pid, "SIGTERM");
+                    }
+                    catch { /* already gone */ }
                 }
-                catch { /* already gone */ }
+                console.log(`✅ Flair stopped (killed PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")})`);
             }
-            console.log(`✅ Flair stopped (killed PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")})`);
         }
         else {
             console.log("Flair is not running.");
@@ -9859,17 +9880,29 @@ export function assertLaunchdServiceOwnedBy(dataDir, label, plistPath, action) {
  * wrong today whenever the port does not match.
  */
 function assertPortInstanceOwnedBy(port, dataDir, listeningPids) {
-    if (resolve(dataDir) === defaultDataDir())
-        return;
+    // (flair#915) Apply the attribution check for ALL data directories, not
+    // just non-default ones. The default-dir bypass was the residual gap that
+    // #910 left behind — it allowed an unattributed SIGTERM on the default
+    // install's port. The old concern (false refusal when hdb.pid is missing)
+    // is actually the RIGHT behavior: no PID file means we cannot attribute the
+    // listener, so we refuse. That is safer than killing the wrong process.
     const expected = readHarperPid(dataDir);
-    if (expected !== null && listeningPids.includes(expected))
+    // No PID file — Harper is not (or was not) running in this directory.
+    // The port is stale or held by something else; refuse to SIGTERM it.
+    if (expected === null) {
+        throw new Error(`refusing to stop the process listening on port ${port}: no hdb.pid under `
+            + `${resolve(dataDir)}, so that is not a running instance. `
+            + `Stopping by port alone would signal a process we cannot attribute. `
+            + `If it is not Flair, stop it manually.`);
+    }
+    // PID file exists — the PID on the port must be Harper.
+    if (listeningPids.includes(expected))
         return;
-    const why = expected === null
-        ? `no hdb.pid under that directory, so it does not look like a running instance`
-        : `its recorded PID ${expected} is not the process listening on ${port}`;
-    throw new Error(`refusing to stop the process listening on port ${port}: it cannot be attributed to ${resolve(dataDir)} (${why}). ` +
-        `Stopping by port alone would signal a different Flair instance. ` +
-        `Pass --port with the port ${resolve(dataDir)} actually serves, or omit --data-dir to operate on the default install.`);
+    throw new Error(`refusing to stop the process listening on port ${port}: its recorded PID ${expected} `
+        + `is not the process listening on ${port}. `
+        + `Stopping by port alone would signal a different instance. `
+        + `Pass --port with the port ${resolve(dataDir)} actually serves, `
+        + `or stop the process manually.`);
 }
 /**
  * Stop the local Flair (Harper) process — launchd `stop` on darwin when a
@@ -10171,7 +10204,11 @@ program
     .option("--purge", "Also remove data and keys (destructive)")
     .action(async (opts) => {
     const platform = process.platform;
-    const port = readPortFromConfig() ?? DEFAULT_PORT;
+    // Use the unified resolver: Harper's config > per-user config > default.
+    // A default of 19926 that is "present but wrong" beats the actual port
+    // Harper is serving on (flair#819). resolveHttpPort reads Harper's own
+    // config in the data directory, which is authoritative.
+    const port = resolveHttpPort({}, "address");
     // Stop first: remove launchd service(s) on macOS, then kill by port on
     // all platforms. Removes BOTH the new instance-scoped plist and a
     // pre-flair#693 legacy plist if present — uninstall's job is to purge
@@ -10198,51 +10235,88 @@ program
     // Kill any process still on the port (covers direct-start, no-service, or
     // failed unload). Listening sockets only, never our own PID — see
     // parseListeningPids (flair#800/flair#905).
+    //
+    // Guard (flair#917): refuse to SIGTERM a PID that cannot be attributed to
+    // this Flair instance. A port is not an identity — something else can hold
+    // it. Killing the wrong PID and then purging data is the whole bug.
+    let refusedKill = false;
     try {
         const { execSync } = await import("node:child_process");
         const pids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
         if (pids.length > 0) {
-            for (const pid of pids) {
-                try {
-                    process.kill(pid, "SIGTERM");
+            // Verify ownership before killing: the PID must match this instance's
+            // recorded PID (hdb.pid). If no PID file exists, Harper is already
+            // stopped and the port is stale — safe to skip.
+            const dataDir = defaultDataDir();
+            const harperPid = readHarperPid(dataDir);
+            if (harperPid !== null) {
+                // PID file exists — the PID on the port must be Harper or we refuse.
+                if (!pids.includes(harperPid)) {
+                    console.log(`⚠️  Process(es) on port ${port} (PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")}) `
+                        + `do not match this Flair instance (PID ${harperPid}). `
+                        + `Not killing — cannot attribute the process to this instance. `
+                        + `Stop the process manually if it is not Flair.`);
+                    refusedKill = true;
                 }
-                catch { }
+                else {
+                    for (const pid of pids) {
+                        try {
+                            process.kill(pid, "SIGTERM");
+                        }
+                        catch { }
+                    }
+                    await new Promise(r => setTimeout(r, 2000));
+                    console.log("✅ Flair process stopped");
+                }
+            }
+            else {
+                // No PID file — Harper is not (or was not) running here.
+                // The port may be stale or held by something else; don't risk killing it.
+                console.log(`⚠️  Process(es) on port ${port} (PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")}) `
+                    + `but no PID file in data directory — not a running Flair instance. `
+                    + `Not killing — stop the process manually if it is not Flair.`);
+                refusedKill = true;
             }
-            // Wait for process to release file handles (RocksDB)
-            await new Promise(r => setTimeout(r, 2000));
-            console.log("✅ Flair process stopped");
         }
     }
     catch { /* not running */ }
-    // Remove config
-    const cfgPath = configPath();
-    if (existsSync(cfgPath)) {
-        const { unlinkSync } = await import("node:fs");
-        unlinkSync(cfgPath);
-        console.log("✅ Config removed");
+    // Always remove per-user config on uninstall.
+    {
+        const cfgPath = configPath();
+        if (existsSync(cfgPath)) {
+            const { unlinkSync } = await import("node:fs");
+            unlinkSync(cfgPath);
+            console.log("✅ Config removed");
+        }
     }
     if (opts.purge) {
-        const { rmSync } = await import("node:fs");
-        const dataDir = defaultDataDir();
-        const keysDir = defaultKeysDir();
-        const flairDir = join(homedir(), ".flair");
-        if (existsSync(dataDir)) {
-            rmSync(dataDir, { recursive: true, force: true });
-            console.log("✅ Data removed: " + dataDir);
-        }
-        if (existsSync(keysDir)) {
-            rmSync(keysDir, { recursive: true, force: true });
-            console.log("✅ Keys removed: " + keysDir);
+        if (refusedKill) {
+            console.log("\n⚠️  Skipping purge: could not attribute the process on port — data preserved.");
+            console.log("Stop the process manually, then re-run: flair uninstall --purge");
         }
-        // Remove .flair dir if empty
-        try {
-            const { readdirSync, rmdirSync } = await import("node:fs");
-            if (existsSync(flairDir) && readdirSync(flairDir).length === 0) {
-                rmdirSync(flairDir);
+        else {
+            const { rmSync } = await import("node:fs");
+            const dataDir = defaultDataDir();
+            const keysDir = defaultKeysDir();
+            const flairDir = join(homedir(), ".flair");
+            if (existsSync(dataDir)) {
+                rmSync(dataDir, { recursive: true, force: true });
+                console.log("✅ Data removed: " + dataDir);
             }
+            if (existsSync(keysDir)) {
+                rmSync(keysDir, { recursive: true, force: true });
+                console.log("✅ Keys removed: " + keysDir);
+            }
+            // Remove .flair dir if empty
+            try {
+                const { readdirSync, rmdirSync } = await import("node:fs");
+                if (existsSync(flairDir) && readdirSync(flairDir).length === 0) {
+                    rmdirSync(flairDir);
+                }
+            }
+            catch { /* non-empty, that's fine */ }
+            console.log("\n🗑️  Flair fully purged");
         }
-        catch { /* non-empty, that's fine */ }
-        console.log("\n🗑️  Flair fully purged");
     }
     else {
         console.log("\nData and keys preserved at ~/.flair/");
@@ -10892,17 +10966,24 @@ program
     else if (versionCheckResult.latest) {
         console.log(`  ${render.icons.ok} flair ${__pkgVersion} is current`);
     }
-    // Helper: try to reach Harper on a given port
+    // Helper: try to reach Harper on a given port.
+    // Must return true ONLY when Harper's /Health endpoint returns 200 OK.
+    // A generic HTTP status > 0 (flair#862) would accept 404 from a Node
+    // inspector on 9229 or any other service — "present but wrong" beats
+    // "absent but correct".
     async function probePort(p) {
         try {
             const res = await fetch(`http://127.0.0.1:${p}/Health`, { signal: AbortSignal.timeout(3000) });
-            return res.status > 0;
+            return res.ok; // 200-299 only — /Health returns { ok: true } on 200
         }
         catch {
             return false;
         }
     }
-    // Helper: discover what port a Harper PID is listening on
+    // Helper: discover what port a Harper PID is listening on.
+    // Scans ALL listening ports for this PID and returns the first one that
+    // responds to /Health with 200 OK. This avoids picking a debug port (9229)
+    // or any non-Flair listener that happens to share the process (flair#862).
     async function discoverPortFromPid(pid) {
         // Defense-in-depth: caller already validates, but re-check here
         if (!/^\d+$/.test(pid))
@@ -10910,9 +10991,16 @@ program
         try {
             const { execSync } = await import("node:child_process");
             const out = execSync(`lsof -aPi -p ${pid} -sTCP:LISTEN -Fn 2>/dev/null || true`, { encoding: "utf-8" });
-            const match = out.match(/:(\d+)$/m);
-            if (match)
-                return Number(match[1]);
+            // Extract all ports from lsof -Fn output (lines like "n127.0.0.1:PORT")
+            const ports = [...out.matchAll(/n(?:\S+):(\d+)/g)].map(m => Number(m[1]));
+            if (ports.length === 0)
+                return null;
+            // Try each port until one responds to /Health with 200 OK
+            for (const port of ports) {
+                if (await probePort(port))
+                    return port;
+            }
+            return null; // No port responded to /Health
         }
         catch { /* ignore */ }
         return null;
@@ -12698,7 +12786,7 @@ memory.command("add [content]")
     .description("Write a new memory row for an agent (content via positional arg or --content)")
     .requiredOption("--agent <id>")
     .option("--content <text>", "memory content (alias for positional arg)")
-    .option("--durability <d>", "standard").option("--tags <csv>")
+    .option("--durability <d>", "permanent|persistent|standard|ephemeral (default standard). Also decides the default visibility when --visibility is omitted: permanent/persistent -> shared, standard/ephemeral -> private").option("--tags <csv>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content)")
     .option("--subject <text>", "one-line title / entity this memory is about")
     .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
@@ -12719,8 +12807,21 @@ memory.command("add [content]")
         body.summary = opts.summary;
     if (opts.subject)
         body.subject = opts.subject;
-    if (opts.visibility)
-        body.visibility = String(opts.visibility).trim();
+    // flair#991: reject an unrecognized --visibility instead of writing it.
+    // `visibility` is a free-form String server-side and the read scope asks
+    // isPrivateVisibility() — an exact match on the literal "private" — so
+    // ANY other string, `--visibility prvate` included, persists a row the
+    // user believes is owner-only and that every agent on the instance can
+    // in fact read. A typo must never widen who can read a memory.
+    if (opts.visibility) {
+        const visibility = String(opts.visibility).trim();
+        if (visibility !== "private" && visibility !== "shared") {
+            console.error(`error: --visibility must be 'private' or 'shared' (got: ${visibility})`);
+            console.error("  omit it to use the durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private");
+            process.exit(1);
+        }
+        body.visibility = visibility;
+    }
     if (opts.derivedFrom) {
         body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
     }
@@ -13098,6 +13199,59 @@ function parseRelativeOrIso(input) {
     const multMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
     return new Date(Date.now() - n * (multMs[unit] ?? 0)).toISOString();
 }
+export function searchScoringFormula(scoring) {
+    return scoring === "composite"
+        ? "semantic × durability-weight × recency-decay × usage-boost"
+        : "cosine similarity only";
+}
+export function buildSearchExplain(record, scoring, now = Date.now()) {
+    const score = typeof record?._score === "number" ? record._score : undefined;
+    const rawScore = typeof record?._rawScore === "number" ? record._rawScore : undefined;
+    // composite mode: server sends both (_rawScore = pre-composite semantic).
+    // raw mode: server sends only _score, and that IS the raw score.
+    const raw = scoring === "composite" ? rawScore : score;
+    const composite = scoring === "composite" ? score : undefined;
+    let ageDays;
+    if (record?.createdAt) {
+        const created = new Date(String(record.createdAt)).getTime();
+        if (Number.isFinite(created))
+            ageDays = Math.max(0, Math.floor((now - created) / 86_400_000));
+    }
+    const explain = {
+        scoring,
+        formula: searchScoringFormula(scoring),
+        durability: record?.durability ?? "standard",
+        usageCount: typeof record?.usageCount === "number" ? record.usageCount : 0,
+    };
+    if (typeof raw === "number")
+        explain.raw = raw;
+    if (typeof composite === "number")
+        explain.composite = composite;
+    if (typeof ageDays === "number")
+        explain.ageDays = ageDays;
+    return explain;
+}
+// Human one-liner for a hit's breakdown. Scoring terms come from the shared
+// builder; the trailing tags/subject/supersedes are record context that json
+// mode already carries at top level, so they're appended here only.
+export function formatSearchExplain(explain, record) {
+    const parts = [];
+    if (typeof explain.raw === "number")
+        parts.push(`raw=${explain.raw.toFixed(3)}`);
+    if (typeof explain.composite === "number")
+        parts.push(`composite=${explain.composite.toFixed(3)}`);
+    parts.push(`durability=${explain.durability}`);
+    if (typeof explain.ageDays === "number")
+        parts.push(`age=${explain.ageDays}d`);
+    parts.push(`usage=${explain.usageCount}`);
+    if (Array.isArray(record?.tags) && record.tags.length > 0)
+        parts.push(`tags=[${record.tags.join(",")}]`);
+    if (record?.subject)
+        parts.push(`subject=${record.subject}`);
+    if (record?.supersedes)
+        parts.push(`supersedes=${record.supersedes}`);
+    return parts.join(" · ");
+}
 program
     .command("search <query>")
     .description("Search memories by meaning (shortcut for memory search) — filterable, with --explain ranking")
@@ -13120,7 +13274,7 @@ program
     .option("--durability <level>", "Filter to permanent|persistent|standard|ephemeral (client-side)")
     .option("--source <name>", "Filter by source/agentId (client-side)")
     // Output modes
-    .option("--explain", "Show score breakdown (composite, raw, durability, age, retrieval) per hit")
+    .option("--explain", "Show score breakdown (raw, composite, durability, age, usage) per hit — also added to --json output as _explain")
     .option("--json", "Output raw JSON array")
     .action(async (query, opts) => {
     try {
@@ -13180,8 +13334,17 @@ program
             results = results.filter((r) => allowed.has(r._source ?? r.agentId ?? ""));
         }
         const mode = render.resolveOutputMode(opts);
+        const scoringMode = payload.scoring === "composite" ? "composite" : "raw";
         if (mode === "json") {
-            console.log(render.asJSON(results));
+            // flair#992: --explain must be honoured here, not silently dropped.
+            // This branch is what every non-TTY caller lands in. The breakdown
+            // rides ALONG the json contract as an opt-in `_explain` key — present
+            // only when the caller typed --explain, so default output is unchanged
+            // — rather than switching output mode behind the caller's back.
+            const out = opts.explain
+                ? results.map((r) => ({ ...r, _explain: buildSearchExplain(r, scoringMode) }))
+                : results;
+            console.log(render.asJSON(out));
             return;
         }
         if (results.length === 0) {
@@ -13233,30 +13396,15 @@ program
             if (meta)
                 console.log(`  ${render.wrap(render.c.dim, "(")} ${meta} ${render.wrap(render.c.dim, ")")}`);
             if (opts.explain) {
-                const parts = [];
-                if (typeof r._rawScore === "number")
-                    parts.push(`raw=${r._rawScore.toFixed(3)}`);
-                if (typeof r._score === "number")
-                    parts.push(`composite=${r._score.toFixed(3)}`);
-                if (typeof r.retrievalCount === "number" && r.retrievalCount > 0)
-                    parts.push(`retrievals=${r.retrievalCount}`);
-                if (r.tags && Array.isArray(r.tags) && r.tags.length > 0)
-                    parts.push(`tags=[${r.tags.join(",")}]`);
-                if (r.subject)
-                    parts.push(`subject=${r.subject}`);
-                if (r.supersedes)
-                    parts.push(`supersedes=${r.supersedes}`);
-                if (parts.length > 0) {
-                    console.log(`    ${render.wrap(render.c.gray, "└─")} ${render.wrap(render.c.dim, parts.join(" · "))}`);
+                const line = formatSearchExplain(buildSearchExplain(r, scoringMode), r);
+                if (line) {
+                    console.log(`    ${render.wrap(render.c.gray, "└─")} ${render.wrap(render.c.dim, line)}`);
                 }
             }
             console.log();
         }
         if (opts.explain) {
-            const formula = payload.scoring === "composite"
-                ? "semantic × durability-weight × recency-decay × retrieval-boost"
-                : "cosine similarity only";
-            console.log(`${render.wrap(render.c.dim, "Scoring:")} ${render.wrap(render.c.bold, payload.scoring)}  ${render.wrap(render.c.dim, `(${formula})`)}`);
+            console.log(`${render.wrap(render.c.dim, "Scoring:")} ${render.wrap(render.c.bold, scoringMode)}  ${render.wrap(render.c.dim, `(${searchScoringFormula(scoringMode)})`)}`);
         }
     }
     catch (err) {
@@ -13404,7 +13552,7 @@ soul.command("set")
     .requiredOption("--agent <id>")
     .requiredOption("--key <key>")
     .requiredOption("--value <value>")
-    .option("--durability <d>", "permanent")
+    .option("--durability <d>", "permanent|persistent|standard|ephemeral (default permanent — soul entries are identity, not working memory)")
     .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
     // PUT /Soul/{agentId:key} (upsert by id), matching flair-client's soul.set().

package/dist/resources/Memory.js

@@ -243,8 +243,27 @@ async function runDedupGate(ctx, content) {
     return findConservativeDedupMatch(ctx, content.agentId, content.content, embedding, cosineThreshold, lexicalThreshold);
 }
 /** Build the final write response: always `written: true`, always includes
- *  `id`, and layers the dedup collision signal on top when present. Never a
- *  code path where a match suppresses these base fields. */
+ *  `id`, `visibility`, and layers the dedup collision signal on top when
+ *  present. Never a code path where a match suppresses these base fields.
+ *
+ *  ── Why `visibility` is in the write response (flair#991) ──────────────────
+ *  Visibility is the one field on a memory the caller most often does NOT
+ *  set and yet most needs to know: the durability-keyed default above stamps
+ *  `private` for a bare write and `shared` for a permanent/persistent one, so
+ *  "who can read this" is decided by a rule the writer never typed. Returning
+ *  it makes the landed value observable on EVERY write surface at once —
+ *  `flair memory add`'s printed JSON, the REST response, the native /mcp
+ *  `memory_store` result, and packages/flair-mcp's `effectiveVisibility` line
+ *  (which read this field all along and had nothing to read, so it always
+ *  rendered "(server default)").
+ *
+ *  Read from `content`, not from `base`: `content.visibility` is the value
+ *  that was actually persisted a few lines earlier, and assigning after the
+ *  `...base` spread means the persisted value wins over anything the storage
+ *  layer echoes back. Omitted (not `null`) when unset, which happens only on
+ *  the put()-over-an-existing-record path where a partial merge carried no
+ *  visibility — reporting `null` there would read as "no one but the owner",
+ *  the opposite of what an absent field means to `isPrivateVisibility()`. */
 function buildWriteResponse(content, result, dedupMatch) {
     const base = result && typeof result === "object" && !Array.isArray(result) ? result : {};
     const response = {
@@ -253,6 +272,9 @@ function buildWriteResponse(content, result, dedupMatch) {
         written: true,
         deduplicated: !!dedupMatch,
     };
+    if (content.visibility !== undefined && content.visibility !== null) {
+        response.visibility = content.visibility;
+    }
     if (dedupMatch) {
         response.matchedId = dedupMatch.matchedId;
         response.matchConfidence = { cosine: dedupMatch.cosine, lexical: dedupMatch.lexical };

package/dist/resources/in-process-api.js

@@ -327,6 +327,7 @@ class InternalAgentTable {
  */
 export class Flair {
     #server;
+    #adminHandle;
     constructor(server) {
         this.#server = server;
     }
@@ -350,7 +351,10 @@ export class Flair {
         // AdminHandle requires an agentId for attribution. We use a sentinel
         // that makes the admin identity visible in audit logs. The caller
         // should use a real admin agent id when possible.
-        return new AdminHandle(this.#server, "_admin");
+        // Cached: the getter returns the same handle on every access so
+        // flair.admin === flair.admin is true (flair#981).
+        this.#adminHandle ??= new AdminHandle(this.#server, "_admin");
+        return this.#adminHandle;
     }
     /**
      * Internal operations — trusted, unattributed, unfiltered.

package/dist/resources/mcp-tools.js

@@ -159,6 +159,37 @@ async function memoryStore(agent, args) {
     // id post-commit through the shared usage ledger).
     if (Array.isArray(args?.usedMemoryIds))
         body.usedMemoryIds = args.usedMemoryIds;
+    // flair#991 writer-controlled sharing intent. Forwarded ONLY when the caller
+    // actually supplied it, so an omitted visibility delegates a byte-identical
+    // body and Memory.post() applies its durability-keyed default.
+    //
+    // ── Why an unrecognized value is REJECTED, not dropped and not passed on ──
+    // `visibility` is a free-form String in schemas/memory.graphql, and the read
+    // scope asks `isPrivateVisibility()` — an exact match on the literal
+    // "private" — so EVERY other string, typos included, reads as non-private
+    // and is returned to every agent on the instance. Both of the softer
+    // options therefore fail in the unsafe direction:
+    //   - forwarding it: `visibility: "prvate"` persists a row the caller
+    //     believes is owner-only and that every agent can in fact read;
+    //   - silently dropping it: falls back to the durability-keyed default,
+    //     which for a permanent/persistent write is `shared` — same outcome,
+    //     with no argument left in the record to explain it.
+    // A misspelled argument must never widen who can read a memory, so the tool
+    // call fails and says so. The allowlist is deliberately not derived from
+    // isPrivateVisibility(): that predicate must stay "is it exactly private"
+    // for the no-visibility-field migration invariant (see
+    // resources/memory-visibility.ts), which is a READ-side rule and cannot
+    // double as a WRITE-side allowlist.
+    if (args?.visibility !== undefined && args?.visibility !== null) {
+        if (args.visibility !== "private" && args.visibility !== "shared") {
+            return {
+                error: "invalid_visibility",
+                status: 400,
+                message: `visibility must be "private" or "shared" (got: ${JSON.stringify(args.visibility)}). Omit it to use the durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private.`,
+            };
+        }
+        body.visibility = args.visibility;
+    }
     return unwrap(await h.post(body));
 }
 /**
@@ -407,6 +438,15 @@ export const TOOLS = {
                     type: { type: "string", enum: ["session", "lesson", "decision", "preference", "fact", "goal"], description: "Memory type (default session)" },
                     durability: { type: "string", enum: ["permanent", "persistent", "standard", "ephemeral"], description: "permanent > persistent > standard > ephemeral (default standard)" },
                     tags: { type: "array", items: { type: "string" }, description: "Tag strings" },
+                    visibility: {
+                        type: "string",
+                        enum: ["private", "shared"],
+                        description: "Writer-controlled sharing intent. Omit to use the server's durability-keyed default: " +
+                            "permanent/persistent -> shared, standard/ephemeral -> private. " +
+                            "private — owner-only, never visible to another agent, even one holding a memory grant. " +
+                            "shared — visible to the owner and every other agent on this instance. " +
+                            "The visibility the write actually landed on is returned in the result.",
+                    },
                     usedMemoryIds: { type: "array", items: { type: "string" }, description: "IDs of memories that informed this write (citation-on-write). Credited via the same deduped usage ledger as record_usage. Optional." },
                 },
                 required: ["content"],

package/docs/embedding-in-a-harper-app.md

@@ -21,6 +21,7 @@ Embedding *adds* the in-process path; `rest: true` keeps serving MCP clients and
 **2. Import the facade and write a memory.**
 
 ```javascript
+import { server } from "harper";
 import { Flair } from "@tpsdev-ai/flair";
 
 const flair = new Flair(server);
@@ -61,6 +62,8 @@ console.log([...server.resources.keys()].sort());   // what Flair registered
 
 One handle per Harper instance. Resolves resources lazily on first use — no lookup at construction time.
 
+**The handle owns nothing.** It holds a reference to the Harper server the caller already owns and acquires no timers, connections, or file handles. There is no `close()` or `dispose()` method. If a future version acquires something releasable, that is a breaking change and will be versioned as one.
+
 ### `flair.as(agentId)`
 
 Returns an `AgentHandle` scoped to that agent. The `agentId` is runtime-validated: missing, empty, blank, or non-string throws `InProcessContextError`.
@@ -85,6 +88,8 @@ planner.agentId;  // "planner"
 
 Admin operations — unfiltered reads, cross-agent writes. Every call site is greppable via `git grep "flair.admin"`.
 
+**The handle is cached** — `flair.admin === flair.admin` is `true`. Access it once and reuse the reference, or access it inline; either is fine.
+
 | Method | Description |
 |---|---|
 | `flair.admin.registerAgent(id, opts?)` | Register an agent through the Agent resource (full Principal shape). |
@@ -301,7 +306,7 @@ The facade wraps a lower-level API that is still available for callers who need
 import { agentContext, adminContext, internalContext, collectionResource } from "@tpsdev-ai/flair/server";
 ```
 
-This is the same seam Flair's own MCP handler and internal tooling use. You should not need it for ordinary agent operations — the facade covers those. Use the primitives when you are building your own abstraction on top of Flair's resources.
+This is the same seam Flair's own MCP handler and internal tooling use. **You should not need it for ordinary agent operations** — the facade covers those. Reach for the primitives when you are building your own abstraction on top of Flair's resources, or when you need the context helpers (`agentContext`, `adminContext`, `internalContext`) to pass into a resource call directly.
 
 ### Resolving a resource
 

package/docs/mcp-clients.md

@@ -203,7 +203,7 @@ Eleven 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. Auto-dedups near-duplicates |
+| `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_get` | Fetch a specific memory by ID |
 | `memory_delete` | Remove a memory |
@@ -214,7 +214,9 @@ Eleven tools, kept deliberately small:
 | `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 |
 
-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 (open-within-org read; see [SECURITY.md](../SECURITY.md)). Mark a memory `visibility: private` to keep it owner-only.
+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)).
+
+Which memories are non-private is decided at write time, and the default is not "shared". `memory_store` defaults `durability` to `standard`, and the server derives visibility from durability — `permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private` — so **a bare `memory_store` call writes an owner-only memory that no other agent can read.** Pass `visibility: "shared"` (or `"private"`, to be explicit) to say what you mean; the tool reports the visibility the write actually landed on so an agent can confirm it rather than assume.
 
 ---
 

package/docs/quickstart.md

@@ -26,7 +26,9 @@ export PATH="$HOME/.npm-global/bin:$PATH"   # add this to ~/.zshrc or ~/.bashrc
 npm install -g @tpsdev-ai/flair
 ```
 
-One install gives you `flair`, `flair-mcp` and the client library.
+One install gives you one command: `flair`.
+
+The stdio adapter your MCP client talks to is a separate package, `@tpsdev-ai/flair-mcp`, and it is deliberately not installed globally — `flair init` wires each client to fetch it on demand with `npx -y @tpsdev-ai/flair-mcp@<version>`, so there is no second global package to keep in step. (The server also has its own `/mcp` endpoint built in, but it is off by default — it registers no route unless `FLAIR_MCP_OAUTH` and a public issuer are set — and no client setup in this guide uses it.) `@tpsdev-ai/flair-client` is a separate package you add to your own project when you want to call Flair from code.
 
 ## 2. Bootstrap Flair and register an agent
 
@@ -110,12 +112,35 @@ flair memory add --agent local "Harper v5 sandbox blocks node:module but process
 {
   "id": "local-1785277247486",
   "written": true,
-  "deduplicated": false
+  "deduplicated": false,
+  "visibility": "private"
 }
 ```
 
 Flair embedded the text locally on write. No network calls.
 
+### Who can read it
+
+`visibility: private` means **only `local` can read this memory** — no other agent on the instance can search it, fetch it by id, or receive it in a bootstrap.
+
+You didn't ask for that, and it isn't a setting you have to remember. Flair derives the default from the memory's **durability**, because how long a memory is meant to last is a good proxy for who it was meant for:
+
+| Durability | Default visibility |
+|---|---|
+| `permanent`, `persistent` | `shared` — a fact or decision worth keeping is worth the team being able to find |
+| `standard`, `ephemeral` — including a bare write with no `--durability` | `private` — working context and scratch state belong to the agent that produced them |
+
+So sharing is a deliberate act, and it takes one flag:
+
+```bash
+flair memory add --agent local --visibility shared \
+  "Release tags are cut from main, never from a release branch"
+```
+
+`--visibility` takes exactly `private` or `shared` — a value it doesn't recognise is an error, not a guess — and overrides the durability rule in both directions. The `visibility` field in the response is the value the memory actually landed on, so read it rather than assuming.
+
+Once a memory is `shared`, **every** agent on this instance can read it, with no grant to set up. That is the shipped model: reads open within one instance, closed at the federation edge. Full picture in [SECURITY.md](../SECURITY.md).
+
 ## 5. Find it back by meaning
 
 ```bash
@@ -131,7 +156,7 @@ You searched for a concept, not the keywords. The line under each hit is its cre
 
 > The percentage is a **rank-fusion score, not a similarity**. It is normalized so the top result is always near 100%. Read it as ordering within these results, never as confidence that the match is good.
 
-Add `--explain` to see the ranking inputs, or `--limit`, `--tag`, `--since 7d` to narrow the search. `flair memory search` runs the same query but always prints raw JSON — use it when piping to a script.
+Add `--explain` to see the ranking inputs per hit — the raw score, the composite score under `--scoring composite`, and the record's durability, age and usage count. When output is JSON (`--json`, or any time stdout is not a terminal) the same breakdown arrives as an `_explain` object on each hit, so scripts get it too. Use `--limit`, `--tag`, `--since 7d` to narrow the search. `flair memory search` runs the same query but always prints raw JSON — use it when piping to a script.
 
 ## 6. Give your agent context on boot
 
@@ -160,7 +185,7 @@ With the MCP server wired up — `flair init` does this automatically for every
 | You want to... | Go to |
 |----------------|-------|
 | Add more agents to the same instance | `flair agent add <id>` |
-| Keep a memory owner-only | `flair memory add --visibility private` — reads are otherwise open to every agent on the instance ([auth.md](auth.md)) |
+| Share a memory with your other agents | `flair memory add --visibility shared` — a bare write lands `private`, see [step 4](#who-can-read-it); a shared one is readable by every agent on the instance, no grant needed ([auth.md](auth.md)) |
 | Import memories from agentic-stack / Mem0 / etc. | [bridges.md](bridges.md) |
 | Sync memories across machines | [federation.md](federation.md) |
 | Integrate with OpenClaw, Claude Code, Cursor | [README.md#integration](../README.md#integration) |

package/docs/the-team.md

@@ -15,7 +15,7 @@ If you're trying to run your own multi-agent team using Flair as the memory laye
 | **Pulse** | EA / intel scanning / coordination | OpenClaw | Claude API | cloud VM |
 | **Nathan** | Founder / product owner / human-in-the-loop | (human) | (human) | wherever |
 
-Every agent has its own Ed25519 identity in Flair. They sign every memory write and every read. **Writes are isolated at the Flair API layer** — Sherlock can't accidentally (or maliciously) write into Pulse's memory, because the signature won't verify for anyone but Pulse. Reads are a different story: within one Flair instance, any verified agent can read any other agent's **non-private** memory — that's the shipped model (open-within-org read, no grant needed), not a gap. An agent keeps something genuinely sensitive owner-only by writing it with `visibility: private`. The hard access boundary is the **federation edge** (a separate Flair instance), not reads within one.
+Every agent has its own Ed25519 identity in Flair. They sign every memory write and every read. **Writes are isolated at the Flair API layer** — Sherlock can't accidentally (or maliciously) write into Pulse's memory, because the signature won't verify for anyone but Pulse. Reads are a different story: within one Flair instance, any verified agent can read any other agent's **non-private** memory — that's the shipped model (open-within-org read, no grant needed), not a gap. Which memories are non-private is decided at write time: visibility defaults from durability, so `permanent`/`persistent` writes land `shared` and `standard`/`ephemeral` writes land `private`. A teammate's scratch context is therefore owner-only until someone shares it deliberately, and an agent keeps something genuinely sensitive owner-only regardless of durability by writing it with `visibility: private`. The hard access boundary is the **federation edge** (a separate Flair instance), not reads within one.
 
 ## How memory flows
 
@@ -41,10 +41,14 @@ Every agent has its own Ed25519 identity in Flair. They sign every memory write
                                    │
                        (every agent can read every other
                         agent's non-private memories —
-                        `visibility: private` stays owner-only)
+                        permanent/persistent land shared,
+                        standard/ephemeral land private,
+                        and private stays owner-only)
 ```
 
-No agent can write into another agent's memory — that's enforced server-side by signature verification, no exceptions. Reads are intentionally open within the org: when Flint commits a piece of strategy, any agent can find it on `memory_search` unless Flint marked it `private`. **By design** — the goal is relevance and findability across the team, not secrecy between roles. An agent that genuinely needs something to stay owner-only (a draft not ready for the team, a sensitive finding pre-disclosure) marks it `visibility: private`; everything else is fair game for any teammate to search.
+No agent can write into another agent's memory — that's enforced server-side by signature verification, no exceptions. Reads are intentionally open within the org: when Flint commits a piece of strategy as a `permanent` or `persistent` memory, it lands `shared` and any agent can find it on `memory_search`. **By design** — the goal is relevance and findability across the team, not secrecy between roles.
+
+The reverse also holds, and it is the part worth internalising: a `standard` or `ephemeral` write lands `private`, so an agent's day-to-day working context is *not* team-searchable by default. Commit something at `permanent`/`persistent` durability, or pass `visibility: shared`, when you mean the team to find it. An agent that needs something owner-only whatever its durability (a draft not ready for the team, a sensitive finding pre-disclosure) marks it `visibility: private` explicitly.
 
 When agents need to *coordinate* — a direct, targeted handoff rather than ambient searchable memory — they pass **explicit messages** through TPS mail (a separate signed delivery channel; see [tpsdev-ai/cli](https://github.com/tpsdev-ai/cli)). That's a different concern from memory visibility: TPS mail is for "I need you, specifically, to see this now"; Flair memory is the shared, searchable record everyone (except where `private`) can draw on later.
 
@@ -106,7 +110,7 @@ The MCP server (`@tpsdev-ai/flair-mcp`) is what makes this orchestrator-agnostic
 
 ## What we deliberately don't do
 
-- **No shared write identity.** Every memory is written and owned by exactly one agent's Ed25519 key — there's no merged "team" identity that can write on another agent's behalf. Reads are a separate story: within the org, any agent can search any other's non-private memory by default (see [SECURITY.md](../SECURITY.md)) — that's intentional, not a leak. TPS mail is still how agents route a message to a *specific* teammate; it's for targeted delivery, not for gating ambient visibility.
+- **No shared write identity.** Every memory is written and owned by exactly one agent's Ed25519 key — there's no merged "team" identity that can write on another agent's behalf. Reads are a separate story: within the org, any agent can search any other's non-private memory by default (see [SECURITY.md](../SECURITY.md)) — that's intentional, not a leak. "Non-private" is set at write time from durability, not by a per-pair grant. TPS mail is still how agents route a message to a *specific* teammate; it's for targeted delivery, not for gating ambient visibility.
 - **No silent LLM-driven memory extraction.** Each agent decides what it remembers. No background "summarize and persist" on every turn — that's how memory drifts away from intent.
 - **No multiple agents on one identity.** "Anvil" and "Anvil-2" would be two separate agentIds with two separate keys. Same workload, different identities, separately-owned memories.
 - **No replay-safe-but-otherwise-unsigned reads.** Every Flair request is Ed25519-signed and verified, including reads. Even on a private network we don't trust the network.

package/docs/troubleshooting.md

@@ -150,7 +150,7 @@ flair agent list
 **Possible causes:**
 1. **Hash-fallback embeddings:** Check `flair status` — if embeddings are in hash mode, semantic search won't work properly. Fix with `flair reembed`.
 2. **Content safety flags:** The memory might have been flagged. Search for it directly: `flair memory list --agent <id>`.
-3. **`visibility: private`:** Reads are open within the org by default — any agent can find any other agent's non-private memories. If the memory was written with `visibility: private`, only its author can find it; search as that agent instead.
+3. **`visibility: private`:** Only its author can find a `private` memory. This is the most common cause when one agent wrote the memory and another is searching for it, because **`private` is what a bare write lands on**: visibility defaults from durability (`permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private`), and a write with no `--durability` is `standard`. Check what the memory landed on with `flair memory list --agent <author> --json` (the table view doesn't show visibility, the JSON records do), then either search as its author, or rewrite it with `--visibility shared` so every agent on the instance can find it (no grant needed — non-private reads are open within the instance).
 4. **Dedup threshold:** If the content is very similar to an existing memory, it may have been deduplicated. Check with `flair memory list`.
 
 ### High memory usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.32.0",
+  "version": "0.33.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",