@tpsdev-ai/flair 0.2.0 → 0.3.0

package/README.md

@@ -3,11 +3,11 @@
 [![CI](https://github.com/tpsdev-ai/flair/actions/workflows/test.yml/badge.svg)](https://github.com/tpsdev-ai/flair/actions/workflows/test.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Identity, memory, and soul for AI agents.**
+**Identity, memory, and soul for AI agents. Runs standalone or as part of a [TPS](https://tps.dev) office.**
 
 Agents forget everything between sessions. Flair gives them a persistent sense of self — who they are, what they know, how they think — backed by cryptographic identity and semantic search.
 
-Built on [Harper](https://github.com/HarperFast/harper). Single process. No sidecars. Zero external API calls for embeddings.
+Built on [Harper](https://harper.fast). Single process. No sidecars. Zero external API calls for embeddings.
 
 ## Why
 
@@ -23,7 +23,7 @@ Flair fixes that:
 
 ## How It Works
 
-Flair is a native [Harper v5](https://github.com/HarperFast/harper) application. Harper handles HTTP, persistence (RocksDB), and application logic in a single process.
+Flair is a native [Harper v5](https://harper.fast) application. Harper handles HTTP, persistence (RocksDB), and application logic in a single process.
 
 ```
 Agent ──[Ed25519-signed request]──▶ Flair (Harper)
@@ -72,7 +72,7 @@ One Flair instance serves any number of agents. Each agent has its own keys, mem
 ## Quick Start
 
 ### Prerequisites
-- [Node.js 20+](https://nodejs.org/) (24+ recommended)
+- [Node.js 22+](https://nodejs.org/)
 
 ### Install & Run
 
@@ -92,53 +92,120 @@ flair status
 
 That's it. Your agent now has identity and memory.
 
-### Use with OpenClaw
+## Integration
+
+Flair works with any agent runtime. Pick the path that fits yours.
+
+### Standalone (Flair CLI)
+
+Use the `flair` CLI directly from any agent that can run shell commands.
+
+```bash
+# Write a memory
+flair memory add --agent mybot --content "learned something important"
+
+# Search by meaning
+flair memory search --agent mybot --q "that important thing"
+
+# Set personality
+flair soul set --agent mybot --key role --value "Security reviewer"
+
+# Cold-start bootstrap (soul + recent memories)
+flair bootstrap --agent mybot --max-tokens 4000
+
+# Backup / restore
+flair backup --admin-pass "$FLAIR_ADMIN_PASS"
+flair restore ./backup.json --admin-pass "$FLAIR_ADMIN_PASS"
+```
+
+### OpenClaw
+
+One command. Zero config.
 
 ```bash
-npm install @tpsdev-ai/openclaw-flair
+openclaw plugins install @tpsdev-ai/openclaw-flair
 ```
 
-Add to your `openclaw.json`:
-```json
-{
-  "memory": {
-    "provider": "@tpsdev-ai/openclaw-flair"
-  }
-}
+The plugin auto-detects your agent identity, provides `memory_store`/`memory_recall`/`memory_get` tools, and injects relevant memories at session start. See the [plugin README](plugins/openclaw-flair/README.md) for details.
+
+### Claude Code / Codex / Cursor
+
+Add a snippet to your `CLAUDE.md` (or `AGENTS.md`, `.codex/instructions.md`, etc.):
+
+```markdown
+## Memory
+
+You have persistent memory via Flair. Use it.
+
+### On session start
+Run: `flair bootstrap --agent mybot --max-tokens 4000`
+This returns your soul + recent memories. Read it — that's your context.
+
+### During work
+- Remember something: `flair memory add --agent mybot --content "what you learned"`
+- Search memory: `flair memory search --agent mybot --q "your query"`
+- Store a lesson: `flair memory add --agent mybot --content "lesson" --type lesson --durability persistent`
+
+### Rules
+- Bootstrap FIRST, before doing anything else
+- Store lessons and decisions immediately — don't wait
+- If you learn something that should survive restarts, write it to Flair
 ```
 
-Your agent will automatically remember things between sessions and recall them by meaning.
+### JavaScript / TypeScript (Client Library)
 
-### Use the CLI directly
+For custom integrations, use the lightweight client — no Harper, no embeddings, just HTTP + auth:
 
 ```bash
-# Write a memory
-flair memory add --agent mybot --content "Harper v5 sandbox blocks bare imports"
+npm install @tpsdev-ai/flair-client
+```
 
-# Search by meaning, not keywords
-flair memory search --agent mybot --q "native module loading issues"
+```typescript
+import { FlairClient } from '@tpsdev-ai/flair-client'
 
-# Set personality
-flair soul set --agent mybot --key role --value "Security reviewer, meticulous and skeptical"
+const flair = new FlairClient({
+  url: 'http://localhost:9926',  // or remote: https://flair.example.com
+  agentId: 'mybot',
+  // key auto-resolved from ~/.flair/keys/mybot.key
+})
 
-# Back up everything
-flair backup --admin-pass "$FLAIR_ADMIN_PASS"
+// Write a memory
+await flair.memory.write('Harper v5 sandbox blocks bare imports')
+
+// Search by meaning
+const results = await flair.memory.search('native module loading')
+
+// Cold-start bootstrap
+const ctx = await flair.bootstrap({ maxTokens: 4000 })
 
-# Restore from backup
-flair restore ./flair-backup-2026-03-15.json --admin-pass "$FLAIR_ADMIN_PASS"
+// Set personality
+await flair.soul.set('role', 'Security reviewer')
 ```
 
-### Cold Start Bootstrap
+See the [client README](packages/flair-client/README.md) for the full API.
 
-Agents can pull their full context on startup via the `BootstrapMemories` endpoint:
+### HTTP API (Any Language)
+
+Flair is a pure HTTP API. Use it from Python, Go, Rust, shell scripts — anything that can make HTTP requests and sign with Ed25519.
 
 ```bash
-curl -H "Authorization: TPS-Ed25519 ..." \
+# Search memories
+curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
+  -X POST http://localhost:9926/SemanticSearch \
+  -d '{"agentId": "mybot", "q": "deployment procedure", "limit": 5}'
+
+# Write a memory
+curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
+  -X PUT http://localhost:9926/Memory/mybot-123 \
+  -d '{"id": "mybot-123", "agentId": "mybot", "content": "...", "durability": "standard"}'
+
+# Bootstrap (soul + recent memories)
+curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
   -X POST http://localhost:9926/BootstrapMemories \
   -d '{"agentId": "mybot", "maxTokens": 4000}'
 ```
 
-Returns soul + recent memories + relevant context as a formatted block. Bounded context regardless of total memory size.
+Auth is Ed25519 — sign `agentId:timestamp:nonce:METHOD:/path` with your private key. See [SECURITY.md](SECURITY.md) for the full protocol.
 
 ## Architecture
 
@@ -154,11 +221,11 @@ flair/
 │   ├── embeddings-provider.ts # In-process nomic embeddings
 │   ├── Memory.ts             # Durability enforcement + auto-embed
 │   ├── Soul.ts               # Permanent-by-default personality
-│   ├── MemorySearch.ts       # Hybrid semantic + keyword search
+│   ├── SemanticSearch.ts     # Hybrid semantic + keyword search
 │   ├── MemoryBootstrap.ts    # Cold start context assembly
 │   └── MemoryFeed.ts         # Real-time memory changes
 ├── plugins/
-│   └── openclaw-memory/       # @tpsdev-ai/openclaw-flair plugin
+│   └── openclaw-flair/        # @tpsdev-ai/openclaw-flair plugin
 └── SECURITY.md                # Threat model + auth documentation
 ```
 
@@ -219,9 +286,9 @@ Integration tests spin up a real Harper instance on a random port, run the test
 
 ## Status
 
-> **Note:** Flair uses [Harper v5](https://github.com/HarperFast/harper), currently in beta. We run it in production daily and track upstream closely. Pin your Harper version.
+> **Note:** Flair uses [Harper v5](https://harper.fast), currently in beta. We run it in production daily and track upstream closely. Pin your Harper version.
 
-Flair is in active development and daily use. We dogfood it — the agents that build Flair use Flair for their own memory and identity. 7 agents, 150+ memories, running continuously since March 2026.
+Flair is in active development and daily use. We dogfood it — the agents that build Flair use Flair for their own memory and identity.
 
 **What works:**
 - ✅ Ed25519 agent identity and auth