@tpsdev-ai/flair 0.26.0 → 0.27.1

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).

package/docs/deployment.md

@@ -0,0 +1,204 @@
+# Deployment Guide
+
+Run Flair on macOS, Linux, or Docker.
+
+## macOS (Apple Silicon)
+
+### Install
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+```
+
+`flair init` will:
+- Download Harper and the nomic-embed-text embedding model
+- Create `~/.flair/` (config, data, keys)
+- Generate admin credentials
+- Install a launchd plist for auto-start on boot
+- Start the server
+
+### Verify
+
+```bash
+flair status
+flair doctor
+```
+
+### Auto-start
+
+`flair init` installs a launchd plist at `~/Library/LaunchAgents/ai.tpsdev.flair.plist`. Flair starts automatically on login and restarts if it crashes.
+
+```bash
+# Manual control
+flair stop
+flair start
+flair restart
+```
+
+### Port
+
+Default port is `19926`. Override during init:
+
+```bash
+flair init --port 8000
+```
+
+Or edit `~/.flair/config.yaml` and restart.
+
+---
+
+## Linux
+
+### Prerequisites
+
+- Node.js >= 22
+- systemd (for auto-start)
+
+### Install
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+```
+
+Same as macOS — detects the platform and generates a systemd unit file instead of a launchd plist.
+
+### Verify
+
+```bash
+flair status
+flair doctor
+```
+
+### Auto-start
+
+The systemd unit file is installed at `~/.config/systemd/user/flair.service`.
+
+```bash
+# Manual control
+systemctl --user start flair
+systemctl --user stop flair
+systemctl --user restart flair
+
+# View logs
+journalctl --user -u flair -f
+```
+
+---
+
+## Docker
+
+### Quick test (from-scratch validation)
+
+```bash
+cd docker/
+./test-from-scratch.sh
+```
+
+This runs a clean install in a container — useful for verifying the install path works on a fresh machine.
+
+### Production Docker
+
+```dockerfile
+FROM node:22-slim
+RUN npm install -g @tpsdev-ai/flair
+RUN flair init --skip-soul
+EXPOSE 19926
+CMD ["flair", "start", "--foreground"]
+```
+
+Note: embeddings run on CPU in Docker (no Metal acceleration). Performance is acceptable for small-to-medium memory stores (< 10K memories).
+
+---
+
+## Harper Fabric
+
+Deploying to a Harper Fabric cluster is a different mechanism from the installs above — `flair deploy` pushes Flair as a cluster component instead of `npm install -g`. To upgrade an already-deployed Fabric instance in place, use `FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> flair upgrade --target <fabric-url>` (or `--fabric-password-file <path>` in place of the env var), not the local upgrade path. Inline `--fabric-user`/`--fabric-password` flags also work but are discouraged — both leak to shell history and `ps`. See [`docs/upgrade.md` — Upgrading a Fabric-deployed instance](upgrade.md#upgrading-a-fabric-deployed-instance) for the full walkthrough, including the automatic post-deploy fleet-convergence sweep.
+
+---
+
+## Remote Access
+
+### SSH tunnel (simplest)
+
+```bash
+ssh -f -N -L 19926:localhost:19926 your-server
+```
+
+Then set `FLAIR_URL=http://localhost:19926` on the client.
+
+### Direct network access
+
+Edit `~/.flair/config.yaml`:
+
+```yaml
+http:
+  port: 19926
+  host: 0.0.0.0  # listen on all interfaces
+```
+
+**Security:** Flair uses Ed25519 authentication. Agents must present a valid signature to read or write. However, the `/Health` endpoint is unauthenticated. For internet-facing deployments, put Flair behind a reverse proxy with TLS.
+
+---
+
+## Configuration
+
+All configuration lives in `~/.flair/`:
+
+```
+~/.flair/
+├── config.yaml          # port, host, embedding model
+├── data/                # Harper database
+├── keys/                # Ed25519 keypairs per agent
+└── backups/             # flair backup output
+```
+
+### Key config options (`~/.flair/config.yaml`)
+
+```yaml
+http:
+  port: 19926            # API port (ops port = this - 1)
+  host: 127.0.0.1        # bind address
+
+clustering:
+  nodeName: flair
+
+logging:
+  level: warn
+  stdStreams: true
+```
+
+### Environment variables
+
+Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.flair.plist` on macOS, the systemd unit on Linux, the component env on Fabric).
+
+| Variable | What it does | When to set it |
+|----------|--------------|----------------|
+| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on (e.g. `https://flair.example.com`). Surfaced in the AdminInstance pane's Endpoints table and used by OAuth metadata + A2A discovery so external clients see a reachable URL. | **Always set on remote / Fabric / VPS deployments.** Local-only installs can leave it unset. |
+| `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. After first start, the persisted user record is the source of truth; rotate via the Harper ops API, not by changing this env var. | Set at install time. See [secrets-and-keys.md](secrets-and-keys.md) for rotation. |
+| `FLAIR_KEY_PASSPHRASE` | Passphrase used to derive the AES-256-GCM key that wraps federation private-key seeds at rest. Auto-generated to `~/.flair/keys/.passphrase` if unset. | Set explicitly for production federation deployments so the passphrase isn't auto-generated and lost on disk wipe. |
+| `HTTP_PORT` | Override the Harper HTTP port. Useful for sandboxes; production deployments should configure the port in `config.yaml` instead. | Rare. |
+
+---
+
+## Backup & Restore
+
+```bash
+# Backup all data (agents, memories, souls)
+flair backup > ~/flair-backup-$(date +%Y%m%d).json
+
+# Restore to a fresh instance
+flair restore < ~/flair-backup-20260405.json
+```
+
+Always backup before upgrades.
+
+---
+
+## Uninstall
+
+```bash
+flair uninstall   # stops server, removes ~/.flair/, removes launchd/systemd service
+npm uninstall -g @tpsdev-ai/flair
+```