@tpsdev-ai/flair 0.25.4 → 0.27.0

package/docs/auth.md

@@ -0,0 +1,178 @@
+# Authentication & Authorization
+
+Flair supports three authentication methods, from simplest to most enterprise-ready.
+
+## Auth across surfaces (read this first)
+
+Different surfaces authenticate differently. The model in one place:
+
+| Surface | Auth | Scope | Notes |
+|---------|------|-------|-------|
+| **CLI / SDK clients** (`flair`, `flair-client`) | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Default, recommended. Signs every request; an agent can never write as another, and reads are scoped to its own memories (any visibility) plus every other agent's **non-private** memories on the instance. |
+| **MCP server** (`@tpsdev-ai/flair-mcp`) | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Same per-agent identity as the CLI — key auto-resolved from `~/.flair/keys/<agent>.key`. |
+| **OpenClaw / pi / Hermes plugins** | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Same secure path; auto-detect agent identity. |
+| **`n8n-nodes-flair`** | **Harper admin-password Basic auth** | ⚠️ **Whole instance, read + write, including `private`** | The admin credential bypasses agent scoping entirely — every workflow gets read/write on the *entire* memory store, including other agents' `private`-marked memories, not just the org-wide non-private pool an Ed25519 identity would see. |
+
+**The default, secure path is Ed25519 per-agent** (see below): each agent holds its own key and signs every request. That guarantees **write isolation** — no agent can write as another — and identity-verified reads. It does **not** mean cross-agent reads are refused: within one Flair instance (one org), any verified agent can read any other agent's memory unless that memory is explicitly marked `visibility: private` (owner-only). The hard access boundary is the **federation edge** (a separate Flair instance / org), not reads within an instance. See [SECURITY.md](../SECURITY.md) for the full model. Use Ed25519 per-agent everywhere you can regardless — it's still what makes writes and identity trustworthy.
+
+### Known limitation — n8n uses admin-password Basic auth
+
+The `n8n-nodes-flair` community node authenticates with the Harper **admin password** (Basic auth), which bypasses agent scoping entirely — not just the org-wide non-private reads an Ed25519 identity already gets. Concretely, an n8n workflow using the admin credential can write memories under *any* agent's identity (no per-agent write isolation) and can read *every* memory including ones marked `visibility: private` (which stay owner-only under normal Ed25519 auth). This is acceptable only when **all** of the following hold:
+
+- The n8n instance is single-tenant and operator-controlled.
+- Workflow inputs are trusted (your own CRM, your own webhook source).
+- Write-forgery and full read access (including `private` memories) are acceptable for the use case.
+
+If any of those don't hold, use Flair's CLI / SDK clients (which support per-agent Ed25519 today) and wait for the n8n credential to gain Ed25519 per-agent auth (planned). Full guidance in [docs/n8n.md](n8n.md#security).
+
+## Ed25519 Agent Auth (Default)
+
+Every agent has an Ed25519 key pair. Requests are signed with `agentId:timestamp:nonce:METHOD:/path` and verified against the agent's registered public key. 30-second replay window with nonce deduplication.
+
+```bash
+# Register an agent
+flair agent add myagent
+
+# The key is stored at ~/.flair/keys/myagent.key
+# Requests are signed automatically by flair-client and the MCP server
+```
+
+This is the default and recommended auth for single-instance deployments.
+
+## Deployment shapes: personal vs org
+
+Flair has no `mode`/`shape` config setting — the shape you get is emergent from *how you provision principals*, not something you declare:
+
+- **Personal (the default).** `flair init` mints ONE agent identity and wires that same `FLAIR_AGENT_ID` into every MCP client it configures (Claude Code, Codex, Gemini, Cursor). One human driving several AI clients ends up with one canonical principal and one Ed25519 keypair — all clients share ownership of the same memory. This is intentional, not a limitation: all clients see each other's private rows (one human's memory, one view), a fact re-asserted from two different clients dedups to one memory, and usage counting treats the principal as one contributor.
+- **Org (multiple real agents).** `flair agent add <id>` mints a distinct principal — its own keypair, its own ownership boundary — for each real agent that should be a separate identity. Wire each principal's own `FLAIR_AGENT_ID` into its own client(s).
+
+Nothing in flair validates which shape you're in; a personal install that later grows into an org just runs `flair agent add` for the new distinct identities it needs.
+
+### Authorship: which client wrote a row
+
+The personal shape's one shared principal means `agentId` alone can't answer "was this written by Claude Code or Codex?" — every write it receives has the same owner. `flair init`'s per-client wiring closes that gap by setting an additional env var per client: `FLAIR_CLIENT` (`"claude-code"` / `"codex"` / `"gemini"` / `"cursor"`). `flair-client` and `flair-mcp` forward it on memory writes as `claimedClient`, and the server folds it into the write's `provenance` blob as `claimed.client` — self-reported, unverified metadata recording *which tool* authored a row, alongside the existing `claimed.model`.
+
+This is deliberately in `claimed`, never `verified`: it carries **zero authority**. It is never read for access control, read-scope, attribution weighting, or dedup decisions — it exists purely for audit/analysis. Absent on any install that predates this field (no backfill, no migration) and absent whenever a client doesn't set `FLAIR_CLIENT`.
+
+The native `/mcp` OAuth surface (see below) doesn't need any client-side wiring at all: the handler stamps `claimed.client` directly from the OAuth token's verified `client_id` claim — the server-generated `flair_cl_...` machine id assigned at Dynamic Client Registration, **not** the user-supplied `client_name` (which the registering client fully controls and could set to anything). Using `client_id` keeps the stamp a stable, server-verified label even though it still only carries `claimed`-level (unverified-by-content) authority.
+
+## OAuth 2.1
+
+Flair includes a built-in OAuth 2.1 authorization server for client integrations (e.g., Claude connecting to Flair as an MCP server).
+
+### Dynamic Client Registration
+
+Clients register automatically on first connection:
+
+```
+POST /OAuthRegister
+Content-Type: application/json
+
+{
+  "client_name": "Claude Desktop",
+  "redirect_uris": ["http://localhost:3000/callback"],
+  "grant_types": ["authorization_code"],
+  "response_types": ["code"],
+  "token_endpoint_auth_method": "none"
+}
+```
+
+Returns `client_id` and `client_secret` (if applicable).
+
+### Authorization Code Flow with PKCE
+
+Standard OAuth 2.1 authorization code flow:
+
+1. Client generates PKCE `code_verifier` and `code_challenge`
+2. Client redirects user to `GET /OAuthAuthorize?client_id=...&code_challenge=...&redirect_uri=...`
+3. User approves (or auto-approves for trusted clients)
+4. Flair redirects back with authorization code
+5. Client exchanges code for access token at `POST /OAuthToken`
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/OAuthRegister` | POST | Dynamic client registration |
+| `/OAuthAuthorize` | GET/POST | Authorization endpoint |
+| `/OAuthToken` | POST | Token endpoint |
+| `/.well-known/oauth-authorization-server` | GET | Server metadata |
+
+## XAA (Enterprise-Managed Authorization)
+
+For organizations using an Identity Provider (IdP), XAA lets the IdP control who accesses Flair and with what scopes.
+
+### How It Works
+
+1. User authenticates with the organization's IdP (Google, Azure AD, Okta)
+2. IdP issues an ID token (JWT) with user identity and group claims
+3. Client sends the ID token to Flair's token endpoint using the `jwt-bearer` grant type
+4. Flair validates the JWT signature, checks issuer/domain, maps to a Principal, and issues a scoped access token
+
+```
+POST /OAuthToken
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
+&assertion=<id-token-from-idp>
+```
+
+### IdP Configuration
+
+Register an IdP with the CLI:
+
+```bash
+flair idp add \
+  --name "Google Workspace" \
+  --issuer "https://accounts.google.com" \
+  --jwks-uri "https://www.googleapis.com/oauth2/v3/certs" \
+  --required-domain "yourcompany.com"
+```
+
+### Supported IdPs
+
+| IdP | Issuer | Domain Claim |
+|-----|--------|-------------|
+| Google Workspace | `https://accounts.google.com` | `hd` (hosted domain) |
+| Azure AD (Entra) | `https://login.microsoftonline.com/{tenant}/v2.0` | `tid` (tenant ID) |
+| Okta / Auth0 | `https://{org}.okta.com` | Issuer-scoped |
+
+### Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `memory:read` | Read memories and search |
+| `memory:write` | Write and delete memories |
+| `memory:admin` | Memory maintenance operations |
+| `principal:read` | View principal list |
+| `principal:admin` | Create/modify/disable principals |
+| `connector:admin` | Manage OAuth clients and IdPs |
+
+### JIT Provisioning
+
+First-time IdP users are automatically created as `unverified` principals. An admin can promote them to `verified` or `admin` via:
+
+```bash
+flair principal promote <principal-id>
+```
+
+### CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `flair idp add` | Register an IdP |
+| `flair idp list` | List configured IdPs |
+| `flair idp remove <id>` | Remove an IdP |
+| `flair idp test <id>` | Test IdP connectivity |
+
+## Web Admin
+
+The web admin at `/AdminDashboard` provides a UI for managing:
+
+- **Principals:** view, promote, disable agents and users
+- **Connectors:** OAuth clients and active sessions
+- **IdP:** enterprise identity provider configuration
+- **Memory:** browse and search stored memories
+- **Instance:** federation status, peer connections
+
+Access requires admin-level authentication (Basic auth with the Harper admin password).

package/docs/bridges.md

@@ -0,0 +1,291 @@
+# Memory Bridges
+
+> Pluggable import/export between Flair and foreign memory systems.
+
+Flair stores memories in its own schema. The rest of the agent ecosystem stores memories too — agentic-stack's `.agent/` directory, Mem0, Letta, Zep, Anthropic memory, and more every week. **Bridges** let Flair speak those formats without a core-code change per integration.
+
+The design goal is *agent-authorable first*: a capable agent should be able to ship a working bridge by reading this doc and running one command.
+
+## Two shapes
+
+| Shape | When to use | Artifact |
+|-------|-------------|----------|
+| **File** (YAML descriptor) | Foreign system stores memories as files on disk (`.agent/`, JSONL, Markdown) | `.flair-bridge/<name>.yaml` in a project, or `~/.flair/bridges/<name>.yaml` user-wide |
+| **API** (TypeScript plugin) | Foreign system exposes an HTTP API (Mem0, Letta, Zep, Anthropic memory) | npm package named `flair-bridge-<name>` |
+
+Pick one. The runtime normalizes both into the same memory-record shape before import.
+
+## The memory record
+
+Every bridge deals in `BridgeMemory` objects. Fields:
+
+```ts
+interface BridgeMemory {
+  // Identity
+  id?: string              // Flair ID if round-tripping; omit on first import
+  foreignId?: string       // original ID in the foreign system (preserved)
+
+  // Content
+  content: string          // REQUIRED
+  subject?: string
+  tags?: string[]
+  visibility?: "private" | "shared" | "public"
+
+  // Durability & lifecycle
+  durability?: "ephemeral" | "standard" | "persistent" | "permanent"
+  createdAt?: string       // ISO-8601; defaults to now on import
+  validFrom?: string
+  validTo?: string
+  expiresAt?: string
+
+  // Ownership
+  agentId?: string         // required on import unless --agent is passed
+
+  // Provenance
+  source?: string
+  derivedFrom?: string[]
+}
+```
+
+**Required on import:** `content` and (`agentId` or the `--agent` flag).
+
+**Flair-owned, never set by a bridge:** `contentHash`, `embedding`, `embeddingModel`, `retrievalCount`, `lastRetrieved`, `promotionStatus`, `_safetyFlags`, any `*By` audit field. These are computed on ingest; if a bridge emits them they're ignored.
+
+## Commands
+
+```bash
+flair bridge list                           # installed bridges
+flair bridge scaffold <name> [--file|--api] # emit starter files
+flair bridge import <name> [src] [opts]     # foreign → Flair (Shape A YAML / built-ins)
+flair bridge test <name> [--fixture <path>] # round-trip diff (coming in slice 3)
+flair bridge export <name> <dst> [opts]     # Flair → foreign (coming in slice 3)
+```
+
+`list`, `scaffold`, and `import` are live as of 0.6.0+. `test` and `export` are stubbed with pointers to slice 3.
+
+Common runtime options for `import`:
+
+| Flag | Meaning |
+|------|---------|
+| `--agent <id>` | Default agent ID for memories that don't carry one (or set `FLAIR_AGENT_ID`) |
+| `--cwd <dir>` | Filesystem root the descriptor's relative paths resolve against (default: cwd) |
+| `--dry-run` | Parse + validate + count, don't write to Flair |
+| `--port <port>` | Harper HTTP port |
+| `--url <url>` | Flair base URL (overrides `--port`) |
+| `--key <path>` | Ed25519 private key path (default: resolved from agent) |
+
+## Your first import (worked example: agentic-stack)
+
+`agentic-stack` ships as a built-in. Drop into a directory that has agentic-stack lessons and run:
+
+```bash
+$ flair bridge list
+  name           kind  source   description
+  agentic-stack  file  builtin  Import agentic-stack lessons.jsonl into Flair persistent memories
+
+$ ls .agent/memory/semantic/
+lessons.jsonl
+
+$ flair bridge import agentic-stack --agent mybot --dry-run
+agentic-stack: would import 47 memories. Re-run without --dry-run to write to Flair.
+
+$ flair bridge import agentic-stack --agent mybot
+  47 imported (lesson-47)
+agentic-stack: imported 47/47 memories.
+```
+
+Each lesson lands as a Flair memory tagged `source: "agentic-stack/lessons"` with `durability: persistent`, the foreign `id` preserved as `foreignId` (so re-importing is idempotent on the same source).
+
+A few things worth knowing:
+
+- **`--agent` is required** unless your descriptor maps an `agentId` column. If you forget, `flair bridge import` errors with a one-line operator-pointer hint plus a structured `BridgeRuntimeError` JSON on stderr.
+- **`--dry-run` is your friend.** Validates the descriptor, parses every record, applies the mapping, but skips the PUT. Use it to confirm the count and check a few records before committing.
+- **Output is throttled** to one progress line every 2 seconds (or every 25 records, whichever comes first), so big imports don't flood your terminal.
+- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [§10 of the spec](../specs/FLAIR-BRIDGES.md#-10-error-format)). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
+
+## Shape A — Declarative YAML
+
+For bridges whose source or target is a directory of files, write a YAML descriptor. No code required.
+
+```yaml
+# .flair-bridge/agentic-stack.yaml
+name: agentic-stack
+version: 1
+kind: file
+description: "agentic-stack .agent/memory/semantic/lessons.jsonl"
+
+detect:
+  anyExists:
+    - ".agent/AGENTS.md"
+    - ".agent/memory/semantic/lessons.jsonl"
+
+import:
+  sources:
+    - path: ".agent/memory/semantic/lessons.jsonl"
+      format: jsonl
+      map:
+        content: "$.claim"
+        subject: "$.topic"
+        tags: "$.tags"
+        foreignId: "$.id"
+        durability: "persistent"
+        source: "agentic-stack/lessons"
+
+export:
+  targets:
+    - path: ".agent/memory/semantic/lessons.jsonl"
+      format: jsonl
+      when: "durability in ['persistent', 'permanent']"
+      map:
+        id: "foreignId ?? id"
+        claim: "content"
+        topic: "subject"
+        tags: "tags"
+```
+
+- **Path expressions:** JSONPath subset — `$.field`, `$.nested.field`, `$.array[*]`.
+- **`when:`** boolean expression over `BridgeMemory` fields. Omit for "always".
+- **Formats supported in 1.0:** `jsonl`, `json`, `yaml`, `markdown-frontmatter`.
+- **What the runtime gives you:** file discovery, format parsing, schema validation, error reporting with `line:column`. You only describe the mapping.
+
+## Shape B — Code plugin
+
+For bridges that talk to HTTP APIs:
+
+```ts
+// flair-bridge-mem0/index.ts
+import type { MemoryBridge, BridgeMemory, BridgeContext } from "@tpsdev-ai/flair";
+
+export const bridge: MemoryBridge = {
+  name: "mem0",
+  version: 1,
+  kind: "api",
+
+  options: {
+    apiKey:  { env: "MEM0_API_KEY", required: true, description: "Mem0 API token" },
+    userId:  { required: true, description: "Mem0 user ID" },
+    baseUrl: { default: "https://api.mem0.ai" },
+  },
+
+  async *import(opts, ctx: BridgeContext) {
+    const res = await ctx.fetch(`${opts.baseUrl}/v1/memories/?user_id=${opts.userId}`, {
+      headers: { Authorization: `Token ${opts.apiKey}` },
+    });
+    const payload = await res.json();
+    for (const m of payload.results ?? []) {
+      yield {
+        foreignId: String(m.id),
+        content: String(m.memory),
+        createdAt: m.created_at,
+        tags: m.categories,
+        source: "mem0",
+      };
+    }
+  },
+
+  async export(memories, opts, ctx) {
+    for await (const m of memories) {
+      await ctx.fetch(`${opts.baseUrl}/v1/memories/`, {
+        method: "POST",
+        headers: { Authorization: `Token ${opts.apiKey}` },
+        body: JSON.stringify({
+          messages: [{ role: "user", content: m.content }],
+          user_id: opts.userId,
+        }),
+      });
+    }
+  },
+};
+```
+
+**`BridgeContext`** gives you:
+
+- `ctx.fetch` — instrumented, rate-limited HTTP. **Always use this instead of the global `fetch`** — it's how the runtime applies per-bridge throttling and audit logging.
+- `ctx.log` — structured `{debug, info, warn, error}` logger.
+- `ctx.cache` — per-bridge key/value cache with optional TTL. Useful for pagination cursors, auth refresh, etc.
+
+Code plugins have no direct filesystem or network access outside `ctx`. This keeps the surface area small and auditable.
+
+## Discovery
+
+`flair bridge list` scans, in precedence order:
+
+1. **Built-ins** shipped inside `@tpsdev-ai/flair`
+2. **Project YAML** — `.flair-bridge/*.yaml` in the current working directory
+3. **User YAML** — `~/.flair/bridges/*.yaml`
+4. **npm packages** — anything matching `flair-bridge-*` or `@scope/flair-bridge-*` under `node_modules/`
+
+Earlier sources win on name conflict. So a built-in adapter can't be accidentally shadowed by a same-named npm package, but a project-local YAML *can* intentionally override an npm bridge for local development.
+
+## Distribution
+
+Publish bridges to npm as `flair-bridge-<name>`. Example `package.json`:
+
+```json
+{
+  "name": "flair-bridge-mem0",
+  "version": "0.1.0",
+  "description": "Flair bridge for Mem0",
+  "main": "index.js",
+  "flair": { "kind": "api", "version": 1 },
+  "peerDependencies": { "@tpsdev-ai/flair": ">=0.6.0" }
+}
+```
+
+There's no registry to curate; npm is the registry. `flair bridge list` surfaces everything installed.
+
+## Round-trip testing
+
+Every bridge ships a fixture. `flair bridge test <name>` will run (slice 2):
+
+1. Import the fixture → `BridgeMemory[]`
+2. Export those memories to a tmp target
+3. Re-import the tmp target → `BridgeMemory[]`
+4. Structural diff on the round-trip-stable fields: `content`, `subject`, `tags`, `durability`
+5. Pass iff the diff is empty
+
+Pass = ship. Iterate against this signal.
+
+## Trust and security
+
+Different sources have different blast radii.
+
+| Source | Default trust |
+|--------|---------------|
+| Built-in | Allowed |
+| Declarative YAML (no code) | Allowed; remote API calls require `--allow-remote` at invocation |
+| Code plugin from npm | Requires `flair bridge allow <name>` on first use |
+| Remote API calls | Always require `--allow-remote` on the invocation |
+
+A code plugin is untrusted JavaScript. The explicit `allow` gate keeps an unreviewed npm package from executing on your machine the first time `flair bridge import` names it. VM isolation is a 1.1 hardening pass.
+
+## Error format
+
+Every bridge error is structured:
+
+```json
+{
+  "bridge": "agentic-stack",
+  "op": "import",
+  "path": ".agent/memory/semantic/lessons.jsonl",
+  "record": 42,
+  "field": "$.claim",
+  "expected": "string",
+  "got": "null",
+  "hint": "lessons.jsonl row 42 has no 'claim' field — skipped"
+}
+```
+
+Printed as a single JSON object per line when `--json`; human-formatted otherwise. Field paths, expected/got, and a hint — that's the minimum an LLM needs to self-correct without operator help.
+
+## Writing your own — the prompt
+
+If you want an agent to write a bridge for you, here's the one-shot prompt:
+
+> You are implementing a Flair bridge for **\<FOREIGN_SYSTEM\>**. Read the sections above on the memory record, on Shape A (file-format targets) or Shape B (API targets) depending on \<FOREIGN_SYSTEM\>, and on round-trip testing. Produce either `.flair-bridge/<name>.yaml` (file targets) or an `index.ts` implementing `MemoryBridge` (API targets). Include a fixture at `fixtures/<name>.fixture.json` or `fixtures/<name>.mock.json`. Run `flair bridge test <name>` and iterate until the round-trip diff is empty.
+
+That's the bar. If an agent can't ship a working bridge from this doc plus the scaffold, the doc is the bug.
+
+## Full spec
+
+The authoritative contract is in [`specs/FLAIR-BRIDGES.md`](../specs/FLAIR-BRIDGES.md). This doc is the user-facing view; the spec covers edge cases, future extensions, and design rationale.

package/docs/claude-code.md

@@ -0,0 +1,202 @@
+# Flair + Claude Code
+
+Give Claude Code persistent memory across sessions. Works with subagents too.
+
+## Setup (5 minutes)
+
+### 1. Install Flair
+
+```bash
+npm install -g @tpsdev-ai/flair
+```
+
+### 2. Initialize
+
+```bash
+flair init
+```
+
+This starts a local Flair server (Harper) and creates `~/.flair/`.
+
+### 3. Create an agent identity
+
+```bash
+# One agent per project, or one shared agent — your call
+flair agent add my-project
+```
+
+This generates an Ed25519 key pair at `~/.flair/keys/my-project.key` and registers the agent with Flair.
+
+### 4. Add to your project's CLAUDE.md
+
+Copy this into your project's `CLAUDE.md` (or `.claude/settings.md`, `AGENTS.md`, etc.):
+
+---
+
+> **Start of CLAUDE.md snippet** — copy everything between the lines.
+
+    ## Memory
+
+    You have persistent memory via Flair. Use it to remember context across sessions.
+
+    ### On session start
+
+    Run this FIRST, before doing anything else:
+
+        flair bootstrap --agent my-project --max-tokens 4000
+
+    Read the output — that's your soul and recent memories.
+
+    ### During work
+
+    - Remember something: `flair memory add --agent my-project --content "what you learned"`
+    - Search memory: `flair search "your query" --agent my-project`
+    - Store a lesson: `flair memory add --agent my-project --content "lesson text" --type lesson --durability persistent`
+    - Store a decision: `flair memory add --agent my-project --content "decision text" --type decision --durability persistent`
+
+    ### What to remember
+
+    - Lessons learned (bugs, workarounds, patterns)
+    - Decisions made (why we chose X over Y)
+    - Project-specific context (architecture, conventions, constraints)
+    - User preferences (coding style, review standards)
+
+    ### What NOT to remember
+
+    - Transient task details (what file am I editing right now)
+    - Things already in the codebase (read the code instead)
+    - Secrets or credentials (never store these in memory)
+
+    ### Durability levels
+
+    - persistent — survives indefinitely. Use for lessons, decisions, preferences.
+    - standard — default. Good for session context, observations.
+    - ephemeral — auto-expires after 24h. Use for temporary notes.
+
+> **End of CLAUDE.md snippet.**
+
+---
+
+That's it. Claude Code will now bootstrap context on start and store important things as it works.
+
+## Multiple Projects
+
+Create a separate agent per project:
+
+```bash
+flair agent add project-alpha
+flair agent add project-beta
+flair agent add infra-ops
+```
+
+Each project's `CLAUDE.md` uses its own agent ID. Memories are fully isolated between projects.
+
+## Subagents
+
+Claude Code subagents (spawned via `/run` or background tasks) can share the parent's memory:
+
+    ### Subagents
+    Subagents share memory with the parent session. Use the same agent ID:
+    FLAIR_AGENT_ID=my-project
+
+    When spawning subagents, pass the agent ID so they can access shared context.
+
+Or give subagents their own identity for isolation:
+
+```bash
+flair agent add my-project-review   # code review subagent
+flair agent add my-project-test     # test runner subagent
+```
+
+## Environment Variables
+
+Instead of passing `--agent` every time, set environment variables:
+
+```bash
+# In your shell profile or .envrc
+export FLAIR_AGENT_ID=my-project
+export FLAIR_URL=http://localhost:19926  # default, only needed if custom
+```
+
+Then the CLAUDE.md simplifies to:
+
+    ## Memory
+    - Bootstrap: `flair bootstrap`
+    - Remember: `flair memory add --content "what you learned"`
+    - Search: `flair search "your query"`
+
+## Soul (Personality / Context)
+
+Want Claude Code to have consistent personality or project context? Set soul entries:
+
+```bash
+# Project context
+flair soul set --agent my-project --key project \
+  --value "E-commerce platform. Rust backend, React frontend. Ship quality over speed."
+
+# Coding standards
+flair soul set --agent my-project --key standards \
+  --value "Always write tests. Prefer composition over inheritance. No any types in TypeScript."
+
+# Review guidelines
+flair soul set --agent my-project --key review \
+  --value "Check for: error handling, edge cases, performance implications, security."
+```
+
+Soul entries are included in every `flair bootstrap` — they're the persistent context that shapes how Claude Code thinks about your project.
+
+## Remote Flair
+
+If you want to share memory across machines (e.g., work laptop + home setup):
+
+```bash
+# On your server
+npm install -g @tpsdev-ai/flair
+flair init
+flair agent add my-project
+
+# On client machines
+npm install -g @tpsdev-ai/flair  # for the CLI
+export FLAIR_URL=http://your-server:19926
+export FLAIR_AGENT_ID=my-project
+# Copy the key from the server:
+scp server:~/.flair/keys/my-project.key ~/.flair/keys/
+```
+
+Or use an SSH tunnel:
+
+```bash
+ssh -f -N -L 19926:localhost:19926 your-server
+# Now FLAIR_URL=http://localhost:19926 works
+```
+
+## Programmatic Access
+
+For custom tooling, use the lightweight client library:
+
+```bash
+npm install @tpsdev-ai/flair-client
+```
+
+```typescript
+import { FlairClient } from '@tpsdev-ai/flair-client'
+
+const flair = new FlairClient({ agentId: 'my-project' })
+
+await flair.memory.write('learned that X causes Y', {
+  type: 'lesson',
+  durability: 'persistent',
+})
+
+const results = await flair.memory.search('what causes Y')
+const context = await flair.bootstrap({ maxTokens: 4000 })
+```
+
+## Tips
+
+- **Bootstrap is cheap.** Run it at the start of every session. It's one HTTP call.
+- **Write lessons immediately.** Don't wait for the session to end — you might not get the chance.
+- **Use durability wisely.** Most things are `standard`. Only promote to `persistent` for things that should survive months.
+- **Search is semantic.** "deployment issues" finds memories about "CI pipeline failures" — you don't need exact keywords.
+- **Temporal queries work.** "What happened today" and "what did we ship recently" are understood.
+- **Dedup is automatic.** Writing the same fact twice won't create duplicates (0.7 similarity threshold).