@tpsdev-ai/flair 0.3.16 → 0.3.19

package/README.md

@@ -128,29 +128,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
-
-You have persistent memory via Flair. Use it.
+### 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" }
+    }
+  }
+}
+```
 
-### On session start
-Run: `flair bootstrap --agent mybot --max-tokens 4000`
-This returns your soul + recent memories. Read it — that's your context.
+Add to your `CLAUDE.md`:
 
-### 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`
+    At the start of every session, run mcp__flair__bootstrap before responding.
 
-### 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)
 
@@ -292,21 +291,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/dist/cli.js

@@ -231,6 +231,7 @@ program
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--data-dir <dir>", "Harper data directory")
     .option("--skip-start", "Skip Harper startup (assume already running)")
+    .option("--skip-soul", "Skip interactive personality setup")
     .action(async (opts) => {
     const agentId = opts.agentId;
     const httpPort = Number(opts.port);
@@ -335,6 +336,43 @@ program
         console.log(`   ${adminPass}`);
     }
     console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
+    // ── First-run soul setup ──────────────────────────────────────────────
+    // Interactive prompts to set initial personality. Skipped with --skip-soul
+    // or when stdin is not a TTY (CI, scripts, piped input).
+    if (!opts.skipSoul && process.stdin.isTTY) {
+        console.log("\n🎭 Set up agent personality (press Enter to skip any):\n");
+        const { createInterface } = await import("node:readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q) => new Promise(r => rl.question(q, r));
+        const role = await ask("   What's this agent's role? (e.g., \"Senior dev, concise and direct\")\n   > ");
+        const project = await ask("   What project is it working on?\n   > ");
+        const standards = await ask("   Any coding standards or preferences?\n   > ");
+        rl.close();
+        // Write non-empty answers as soul entries
+        const soulEntries = [];
+        if (role.trim())
+            soulEntries.push(["role", role.trim()]);
+        if (project.trim())
+            soulEntries.push(["project", project.trim()]);
+        if (standards.trim())
+            soulEntries.push(["standards", standards.trim()]);
+        if (soulEntries.length > 0) {
+            console.log("");
+            for (const [key, value] of soulEntries) {
+                try {
+                    await authFetch(httpUrl, agentId, privPath, "PUT", `/Soul/${agentId}:${key}`, { id: `${agentId}:${key}`, agentId, key, value, createdAt: new Date().toISOString() });
+                    console.log(`   ✓ soul:${key} set`);
+                }
+                catch (err) {
+                    console.warn(`   ⚠ soul:${key} failed: ${err.message}`);
+                }
+            }
+            console.log(`\n   ${soulEntries.length} soul entries saved. Bootstrap will include them.`);
+        }
+        else {
+            console.log("\n   No soul entries — you can add them later with: flair soul set --agent " + agentId + " --key role --value \"...\"");
+        }
+    }
     console.log(`\n   Claude Code: Add to your CLAUDE.md:`);
     console.log(`     At the start of every session, run mcp__flair__bootstrap before responding.`);
     console.log(`\n   MCP config (.mcp.json):`);

package/dist/resources/embeddings-provider.js

@@ -1,24 +1,48 @@
 /**
  * embeddings-provider.ts
  *
- * Thin wrapper around harper-fabric-embeddings for Flair resources.
- * harper-fabric-embeddings is loaded by Harper as a sub-component
- * (declared in config.yaml). It downloads the model and initializes
- * in the background. We just call embed() — if it's not ready yet,
- * we return null and the caller handles it gracefully.
+ * Wrapper around harper-fabric-embeddings for Flair resources.
+ *
+ * Harper loads resources in a VM sandbox with a separate module cache from
+ * the main thread. This means our import of harper-fabric-embeddings gets
+ * a different (uninitialized) instance from the one Harper initialized via
+ * handleApplication in config.yaml.
+ *
+ * Solution: we call hfe.init() ourselves on first use. The model is already
+ * on disk (downloaded by Harper's plugin loader), so init just loads the
+ * native binary and model file — no download needed.
  */
 import * as hfe from "harper-fabric-embeddings";
+import { join } from "node:path";
+let _ready = false;
+async function ensureInit() {
+    if (_ready)
+        return;
+    try {
+        // Check if already initialized (e.g. shared context)
+        hfe.dimensions();
+        _ready = true;
+        return;
+    }
+    catch {
+        // Not initialized — init with modelsDir pointing to where Harper's
+        // plugin loader downloaded the model (process.cwd() is the app dir)
+        const modelsDir = join(process.cwd(), "models");
+        await hfe.init({ modelsDir });
+        _ready = true;
+    }
+}
 /**
  * Generate an embedding vector for the given text.
- * Returns null if the embedding engine isn't ready yet (model still loading)
- * or not available on this platform. Never gives up permanently — each call
- * checks independently.
+ * Returns null if the embedding engine isn't available on this platform.
  */
 export async function getEmbedding(text) {
     try {
+        await ensureInit();
         return await hfe.embed(text);
     }
-    catch {
+    catch (err) {
+        console.error(`[embeddings] embed failed: ${err.message}`);
         return null;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.3.16",
+  "version": "0.3.19",
   "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",
   "license": "Apache-2.0",
@@ -29,7 +29,6 @@
   },
   "files": [
     "dist/",
-    "resources/",
     "schemas/",
     "config.yaml",
     "LICENSE",