@tpsdev-ai/flair 0.3.17 → 0.4.0

package/README.md

@@ -88,6 +88,12 @@ flair agent add mybot --name "My Bot" --role assistant
 
 # Check everything is working
 flair status
+
+# Lifecycle management
+flair stop          # Stop the Flair instance
+flair restart       # Restart the Flair instance
+flair uninstall     # Remove the service (keeps data)
+flair uninstall --purge  # Remove everything including data and keys
 ```
 
 That's it. Your agent now has identity and memory.
@@ -128,29 +134,28 @@ openclaw plugins install @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
+### Claude Code / Codex / Cursor (MCP)
+
+Install the MCP server for native tool integration:
+
+```json
+// .mcp.json in your project root
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["@tpsdev-ai/flair-mcp"],
+      "env": { "FLAIR_AGENT_ID": "mybot" }
+    }
+  }
+}
+```
 
-You have persistent memory via Flair. Use it.
+Add to your `CLAUDE.md`:
 
-### On session start
-Run: `flair bootstrap --agent mybot --max-tokens 4000`
-This returns your soul + recent memories. Read it — that's your context.
+    At the start of every session, run mcp__flair__bootstrap before responding.
 
-### 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
-```
+Claude Code gets native tools: `memory_store`, `memory_search`, `bootstrap`, `soul_set`, and more. See the [MCP README](packages/flair-mcp/README.md) and [Claude Code guide](docs/claude-code.md).
 
 ### JavaScript / TypeScript (Client Library)
 
@@ -164,7 +169,7 @@ npm install @tpsdev-ai/flair-client
 import { FlairClient } from '@tpsdev-ai/flair-client'
 
 const flair = new FlairClient({
-  url: 'http://localhost:9926',  // or remote: https://flair.example.com
+  url: 'http://localhost:19926',  // or remote: https://flair.example.com
   agentId: 'mybot',
   // key auto-resolved from ~/.flair/keys/mybot.key
 })
@@ -191,17 +196,17 @@ Flair is a pure HTTP API. Use it from Python, Go, Rust, shell scripts — anythi
 ```bash
 # Search memories
 curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
-  -X POST http://localhost:9926/SemanticSearch \
+  -X POST http://localhost:19926/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 \
+  -X PUT http://localhost:19926/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 \
+  -X POST http://localhost:19926/BootstrapMemories \
   -d '{"agentId": "mybot", "maxTokens": 4000}'
 ```
 
@@ -246,15 +251,22 @@ flair init
 
 Your data stays on your machine. Best for personal agents, dev teams, and privacy-first setups. Flair runs as a single Harper process — no Docker, no cloud, no external services.
 
+#### Custom Ports
+If the default port (`19926`) is already in use, initialize with a custom port:
+```bash
+flair init --port 8000
+```
+Flair will automatically remember this port for future CLI commands by saving it to `~/.flair/config.yaml`.
+
 ### Remote Server
 
 Run Flair on a VPS or cloud instance. Agents connect over HTTPS:
 
 ```bash
 # On the server
-flair init --port 9926
+flair init --port 19926
 # Agents connect with:
-FLAIR_URL=https://your-server:9926 flair agent add mybot
+FLAIR_URL=https://your-server:19926 flair agent add mybot
 ```
 
 Good for teams with multiple machines or always-on agents.
@@ -292,21 +304,25 @@ Flair is in active development and daily use. We dogfood it — the agents that
 
 **What works:**
 - ✅ Ed25519 agent identity and auth
-- ✅ CLI: init, agent add/remove/rotate-key, status, backup/restore, grant/revoke
-- ✅ Memory CRUD with durability enforcement
-- ✅ In-process semantic embeddings (768-dim nomic-embed-text, Metal GPU)
-- ✅ Hybrid search (semantic + keyword)
+- ✅ CLI: init, agent add/remove/rotate-key, status, backup/restore, export/import, grant/revoke
+- ✅ Memory CRUD with durability enforcement and near-duplicate detection
+- ✅ In-process semantic embeddings (768-dim nomic-embed-text via harper-fabric-embeddings)
+- ✅ Hybrid search (semantic + keyword + temporal intent detection)
 - ✅ Soul (permanent personality/values)
 - ✅ Real-time feeds (WebSocket/SSE)
 - ✅ Agent-scoped data isolation
-- ✅ Cold start bootstrap
+- ✅ Cold start bootstrap with adaptive time window
 - ✅ OpenClaw memory plugin
+- ✅ MCP server for Claude Code / Cursor / Windsurf
+- ✅ Lightweight client library (`@tpsdev-ai/flair-client`)
+- ✅ Portable agent identity (export/import between instances)
+- ✅ `flair --version`, `flair upgrade`
 
 **What's next:**
+- [ ] First-run soul wizard (interactive personality setup)
+- [ ] Git-backed memory sync
 - [ ] Encryption at rest (opt-in AES-256-GCM per memory)
-- [ ] Pluggable embedding backends (OpenAI, Cohere, local)
 - [ ] Harper Fabric deployment (managed multi-office)
-- [ ] Scheduled automatic backups
 
 ## License
 

package/config.yaml

@@ -1,8 +1,10 @@
 name: flair
 rest: true
 
-http:
-  port: 8787
+## Port is configured via CLI (flair init --port) or HTTP_PORT env var.
+## Omitted here to avoid conflicts with different deployment scenarios.
+# http:
+#   port: 19926
 
 graphqlSchema:
   files: schemas/*.graphql