@tpsdev-ai/flair 0.6.2 → 0.8.0

package/README.md

@@ -160,19 +160,19 @@ One command. Zero config.
 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.
+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](packages/openclaw-flair/README.md) for details.
 
-### Claude Code / Codex / Cursor (MCP)
+### Claude Code / Gemini CLI / OpenAI Codex CLI / Cursor (MCP)
 
-Install the MCP server for native tool integration:
+One MCP server, many CLIs. Install the MCP server for native tool integration in any MCP-capable client:
 
 ```json
-// .mcp.json in your project root
+// .mcp.json in your project root (Claude Code / Cursor format)
 {
   "mcpServers": {
     "flair": {
       "command": "npx",
-      "args": ["@tpsdev-ai/flair-mcp"],
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
       "env": { "FLAIR_AGENT_ID": "mybot" }
     }
   }
@@ -183,7 +183,20 @@ Add to your `CLAUDE.md`:
 
     At the start of every session, run mcp__flair__bootstrap before responding.
 
-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).
+Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The MCP server exposes `memory_store`, `memory_search`, `memory_get`, `memory_delete`, `bootstrap`, `soul_set`, `soul_get`.
+
+For per-CLI config snippets (Gemini CLI's `~/.gemini/settings.json`, Codex CLI's `~/.codex/config.toml`, etc.), see **[docs/mcp-clients.md](docs/mcp-clients.md)**. For a deeper Claude Code walk-through with `CLAUDE.md` patterns, see [docs/claude-code.md](docs/claude-code.md).
+
+### n8n (community node)
+
+Use Flair as the memory backend for n8n's AI Agent. Same memories readable from Claude Code and OpenClaw — that's the point.
+
+```bash
+# In n8n: Settings → Community Nodes → Install
+@tpsdev-ai/n8n-nodes-flair
+```
+
+Two nodes ship: **Flair Chat Memory** (Memory port, conversation buffer) and **Flair Search** (Tool port, semantic search + get-by-subject). Setup walkthrough, subject/sessionId patterns, and security guidance in **[docs/n8n.md](docs/n8n.md)**.
 
 ### JavaScript / TypeScript (Client Library)
 

package/dist/bridges/builtins/index.js

@@ -1,17 +1,20 @@
 /**
  * Built-in bridge registry.
  *
- * Each built-in ships as a typed `YamlBridgeDescriptor` (see
- * `agentic-stack.ts`). The CLI passes this registry to `discover()` so
- * built-ins surface in `flair bridge list` alongside user-authored
- * bridges, and to the import/export runtime so it knows how to load
- * the descriptor for a built-in name.
+ * Each built-in ships as either a `YamlBridgeDescriptor` (_shape A_: declarative YAML)
+ * or a `MemoryBridge` (shape B: TypeScript code plugin). The CLI passes this
+ * registry to `discover()` so built-ins surface in `flair bridge list` alongside
+ * user-authored bridges, and to the import/export runtime so it knows how to
+ * load the descriptor/plugin for a built-in name.
  *
- * To add a new built-in: write `src/bridges/builtins/<name>.ts`
- * exporting a `YamlBridgeDescriptor`, then register it here.
+ * To add a new built-in:
+ *   - YAML: write `src/bridges/builtins/<name>.ts` exporting a `YamlBridgeDescriptor`
+ *   - Code plugin: write `src/bridges/builtins/<name>.ts` exporting a `MemoryBridge`
+ *   Then register it here. See specs/FLAIR-BRIDGES.md §2 for shapes A/B.
  */
 import { agenticStackDescriptor } from "./agentic-stack.js";
-function builtin(d) {
+import { markdownMemoryBridge } from "./markdown.js";
+function builtinDescriptor(d) {
     return {
         discovered: {
             name: d.name,
@@ -21,14 +24,28 @@ function builtin(d) {
             description: d.description,
             version: d.version,
         },
-        descriptor: d,
+        descriptorOrPlugin: d,
+    };
+}
+function builtinPlugin(p) {
+    return {
+        discovered: {
+            name: p.name,
+            kind: p.kind,
+            source: "builtin",
+            path: `(builtin:${p.name})`,
+            description: p.description,
+            version: p.version,
+        },
+        descriptorOrPlugin: p,
     };
 }
 /** All bridges shipped inside @tpsdev-ai/flair. Order doesn't matter. */
 export const BUILTINS = [
-    builtin(agenticStackDescriptor),
+    builtinDescriptor(agenticStackDescriptor),
+    builtinPlugin(markdownMemoryBridge),
 ];
-/** Map name → descriptor for O(1) runtime lookup. */
+/** Map name → descriptor/plugin for O(1) runtime lookup. */
 export const BUILTIN_BY_NAME = new Map(BUILTINS.map((b) => [b.discovered.name, b]));
 /** What `discover()` consumes for the `builtins` option. */
 export function builtinDiscoveryRecords() {

package/dist/bridges/builtins/markdown.js

@@ -0,0 +1,66 @@
+/**
+ * Built-in bridge: markdown
+ *
+ * Imports markdown files from a directory into Flair memories.
+ * Each .md file becomes one memory with content sans front-matter,
+ * type/tags/subject/createdAt derived from front-matter fields.
+ *
+ * Round-trip stable: export produces equivalent markdown files.
+ */
+import { promises as fsp } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseRecords } from "../runtime/formats.js";
+import { BridgeRuntimeError } from "../types.js";
+export async function* importFromDirectory(opts, ctx) {
+    // Resolve source directory
+    const sourceDir = typeof opts.source === "string" ? opts.source : join(homedir(), "notes");
+    ctx.log.info(`scanning markdown directory`, { path: sourceDir });
+    // Scan directory for .md files
+    let files;
+    try {
+        const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
+        files = entries
+            .filter((e) => e.isFile() && e.name.endsWith(".md"))
+            .map((e) => join(sourceDir, e.name));
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            ctx.log.warn(`source directory does not exist`, { path: sourceDir });
+            return;
+        }
+        throw new BridgeRuntimeError({
+            bridge: "markdown",
+            op: "import",
+            field: "source",
+            expected: "readable directory",
+            got: err?.code ?? "error",
+            hint: `could not read source directory ${sourceDir}: ${err?.message ?? err}`,
+        });
+    }
+    ctx.log.info(`found markdown files`, { count: files.length });
+    for (const filePath of files) {
+        ctx.log.debug(`processing file`, { path: filePath });
+        let raw;
+        try {
+            raw = await fsp.readFile(filePath, "utf-8");
+        }
+        catch (err) {
+            ctx.log.warn(`could not read file, skipping`, { path: filePath, error: err?.message });
+            continue;
+        }
+        // Use parseRecords from formats.ts for consistent parsing
+        const parser = parseRecords("markdown", filePath, "markdown-frontmatter");
+        for await (const { record } of parser) {
+            yield record;
+        }
+    }
+}
+// Export as a code-plugin MemoryBridge (Shape B)
+export const markdownMemoryBridge = {
+    name: "markdown",
+    version: 1,
+    kind: "file",
+    description: "Import markdown files with front-matter into Flair memories",
+    import: importFromDirectory,
+};

package/dist/bridges/runtime/context.js

@@ -28,8 +28,9 @@ export function makeContext(opts) {
             timestamp: new Date().toISOString(),
         });
     };
+    const wrappedFetch = ((input, init) => fetch(input, init));
     return {
-        fetch: (input, init) => fetch(input, init),
+        fetch: wrappedFetch,
         log: {
             debug: log("debug"),
             info: log("info"),

package/dist/bridges/runtime/formats.js

@@ -36,15 +36,8 @@ export async function* parseRecords(bridge, path, format) {
             yield* parseYamlRecords(bridge, path, raw);
             return;
         case "markdown-frontmatter":
-            throw new BridgeRuntimeError({
-                bridge,
-                op: "import",
-                path,
-                field: "format",
-                expected: "jsonl | json | yaml",
-                got: "markdown-frontmatter",
-                hint: "markdown-frontmatter parser lands in slice 2b along with its reference adapter",
-            });
+            yield* parseMarkdownFrontmatter(bridge, path, raw);
+            return;
     }
 }
 // ─── jsonl ────────────────────────────────────────────────────────────────────
@@ -134,3 +127,98 @@ function* parseYamlRecords(bridge, path, raw) {
 function truncate(s, n) {
     return s.length > n ? s.slice(0, n - 1) + "…" : s;
 }
+// ─── markdown-frontmatter ─────────────────────────────────────────────────────
+/**
+ * Parse a markdown file with optional front-matter.
+ * Front-matter is YAML delimited by --- at the start of the file.
+ * Returns an object with content, type, tags, subject, createdAt, derivedFrom.
+ */
+function* parseMarkdownFrontmatter(bridge, path, raw) {
+    const lines = raw.split(/\r?\n/);
+    // Check for front-matter delimiter
+    if (!lines[0] || lines[0].trim() !== "---") {
+        // No front-matter - treat entire file as content
+        yield {
+            record: {
+                content: raw,
+                type: "fact",
+                subject: path.split("/").pop()?.replace(/\.md$/i, "") ?? "",
+                createdAt: new Date().toISOString(),
+                derivedFrom: [path],
+                foreignId: path,
+            },
+            recordIndex: 1,
+        };
+        return;
+    }
+    // Skip the opening ---
+    let i = 1;
+    // Find closing ---
+    let fmLines = [];
+    while (i < lines.length) {
+        if (lines[i]?.trim() === "---") {
+            i++; // skip closing ---
+            break;
+        }
+        fmLines.push(lines[i]);
+        i++;
+    }
+    // Parse front-matter YAML
+    let fm;
+    try {
+        const fmText = fmLines.join("\n");
+        const parsed = yaml.load(fmText);
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error("front-matter is not a valid YAML object");
+        }
+        fm = parsed;
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "import",
+            path,
+            record: 1,
+            field: "front-matter",
+            expected: "valid YAML",
+            got: err?.name ?? "parse error",
+            hint: `front-matter parse failed: ${err?.message ?? err}`,
+        });
+    }
+    // Extract content (everything after front-matter)
+    const content = lines.slice(i).join("\n");
+    // Build record from front-matter with defaults
+    let createdAt;
+    if (fm.date instanceof Date) {
+        createdAt = fm.date.toISOString();
+    }
+    else if (typeof fm.date === "string") {
+        createdAt = fm.date;
+    }
+    else {
+        createdAt = new Date().toISOString();
+    }
+    const record = {
+        content,
+        type: typeof fm.type === "string" ? fm.type : "fact",
+        subject: typeof fm.title === "string" ? fm.title : path.split("/").pop()?.replace(/\.md$/i, "") ?? "",
+        createdAt,
+        derivedFrom: [path],
+        foreignId: path, // Stable identifier for idempotent imports
+    };
+    // Handle tags - can be array or string
+    if (typeof fm.tags === "string") {
+        // Scalar string - split on comma or treat as single tag
+        const tagStr = fm.tags.trim();
+        if (tagStr.includes(",")) {
+            record.tags = tagStr.split(/,\s*/).filter((t) => t.length > 0);
+        }
+        else if (tagStr.length > 0) {
+            record.tags = [tagStr];
+        }
+    }
+    else if (Array.isArray(fm.tags)) {
+        record.tags = fm.tags.filter((t) => typeof t === "string");
+    }
+    yield { record, recordIndex: 1 };
+}

package/dist/bridges/runtime/load-bridge.js

@@ -29,7 +29,15 @@ export async function loadBridge(discovered, opts = {}) {
                     hint: `built-in "${discovered.name}" not in the registry — likely code drift between discover.ts and builtins/index.ts`,
                 });
             }
-            return { kind: "yaml", descriptor: builtin.descriptor, source: discovered };
+            // Dispatch on the type of descriptorOrPlugin
+            if (typeof builtin.descriptorOrPlugin.import === "function") {
+                // Code plugin (MemoryBridge)
+                return { kind: "code", plugin: builtin.descriptorOrPlugin, source: discovered };
+            }
+            else {
+                // YAML descriptor
+                return { kind: "yaml", descriptor: builtin.descriptorOrPlugin, source: discovered };
+            }
         }
         case "project-yaml":
         case "user-yaml": {
@@ -40,15 +48,17 @@ export async function loadBridge(discovered, opts = {}) {
             if (!opts.skipAllowCheck) {
                 const verdict = await verifyAllow(discovered, { path: opts.allowListPath });
                 if (!verdict.ok) {
+                    const reason = verdict.reason;
+                    const failVerdict = verdict;
                     throw new BridgeRuntimeError({
                         bridge: discovered.name,
                         op: "import",
                         path: discovered.path,
                         field: "(trust)",
-                        expected: verdict.reason === "not-allowed" ? "allow-listed code plugin" : "approved package at recorded location/digest",
-                        got: verdict.reason,
-                        hint: trustHint(discovered.name, verdict),
-                        context: trustContext(discovered, verdict),
+                        expected: reason === "not-allowed" ? "allow-listed code plugin" : "approved package at recorded location/digest",
+                        got: reason,
+                        hint: trustHint(discovered.name, failVerdict),
+                        context: trustContext(discovered, failVerdict),
                     });
                 }
             }