@tpsdev-ai/n8n-nodes-flair 0.8.0

package/README.md

@@ -0,0 +1,33 @@
+# @tpsdev-ai/n8n-nodes-flair
+
+n8n community node — use [Flair](https://github.com/tpsdev-ai/flair) as your AI Agent's memory backend.
+
+## Nodes
+
+- **Flair Chat Memory** — n8n AI Agent Memory port. Stores chat history in Flair, replayable across runs and readable from Claude Code, OpenClaw, and any other Flair client. LangChain `BufferWindowMemory` under the hood.
+- **Flair Search** — n8n AI Agent Tool port. Two operations:
+  - *Semantic Search* — finds memories ranked by similarity to a natural-language query.
+  - *Get By Subject* — lists memories filtered by subject, ordered by recency.
+  - *Get By Tag* — coming in a follow-up once `flair-client.memory.list` exposes a `tags` filter (tracked in the [spec](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) §6).
+
+## Installation
+
+```sh
+npm install @tpsdev-ai/n8n-nodes-flair
+```
+
+Then restart your n8n instance. The Flair API credential will appear under **Credentials** → **New** → **Flair API**.
+
+Full setup walkthrough, subject/sessionId patterns, and security guidance are in [`docs/n8n.md`](https://github.com/tpsdev-ai/flair/blob/main/docs/n8n.md) in the Flair repo.
+
+## Credential setup
+
+1. **Base URL** — your Flair instance, e.g. `http://localhost:9926`
+2. **Agent ID** — the logical identity that will own memories written from this n8n workspace. Workflows that share an Agent ID share memory ownership.
+3. **Admin Password** — your Flair (Harper) admin password. **This grants read/write access to the entire instance.** For production with untrusted workflow inputs, wait for Ed25519 per-agent auth (planned).
+
+The credential test hits `/Memory` (auth-required) — you'll know it works when the test succeeds.
+
+## License
+
+Apache-2.0

package/dist/credentials/FlairApi.credentials.d.ts

@@ -0,0 +1,30 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+/**
+ * Flair API credential — v1 Harper admin-password authentication.
+ *
+ * SECURITY NOTE: the admin password grants read/write to the entire Flair
+ * instance, not just the specified agentId. The blast radius is the whole
+ * memory store. This is acceptable for v1 / proof-of-concept where the
+ * operator controls the n8n workflow inputs, but planned Ed25519 per-agent
+ * auth should land before any deployment with sensitive memories from
+ * untrusted workflow inputs.
+ *
+ * The agentId field controls memory ownership — workflows that share an
+ * agentId share memory ownership, allowing "this assistant remembers"
+ * patterns across workflows. Use distinct agentIds when isolation matters.
+ *
+ * AUTH FLOW: Flair (Harper) accepts `Authorization: Basic` with the
+ * admin user (`admin`) and the admin password. We pass the password in
+ * via the `adminPassword` credential field; the Basic-auth header is
+ * constructed via the n8n expression engine. The credential test hits
+ * `/Memory` (auth-required) — `/Health` is unauthenticated, so testing
+ * against it would silently pass with wrong credentials.
+ */
+export declare class FlairApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/FlairApi.credentials.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlairApi = void 0;
+/**
+ * Flair API credential — v1 Harper admin-password authentication.
+ *
+ * SECURITY NOTE: the admin password grants read/write to the entire Flair
+ * instance, not just the specified agentId. The blast radius is the whole
+ * memory store. This is acceptable for v1 / proof-of-concept where the
+ * operator controls the n8n workflow inputs, but planned Ed25519 per-agent
+ * auth should land before any deployment with sensitive memories from
+ * untrusted workflow inputs.
+ *
+ * The agentId field controls memory ownership — workflows that share an
+ * agentId share memory ownership, allowing "this assistant remembers"
+ * patterns across workflows. Use distinct agentIds when isolation matters.
+ *
+ * AUTH FLOW: Flair (Harper) accepts `Authorization: Basic` with the
+ * admin user (`admin`) and the admin password. We pass the password in
+ * via the `adminPassword` credential field; the Basic-auth header is
+ * constructed via the n8n expression engine. The credential test hits
+ * `/Memory` (auth-required) — `/Health` is unauthenticated, so testing
+ * against it would silently pass with wrong credentials.
+ */
+class FlairApi {
+    name = 'flairApi';
+    displayName = 'Flair API';
+    documentationUrl = 'https://github.com/tpsdev-ai/flair#n8n';
+    properties = [
+        {
+            displayName: 'Base URL',
+            name: 'baseUrl',
+            type: 'string',
+            default: 'http://localhost:9926',
+            required: true,
+            description: 'The Flair instance URL. Use http://localhost:9926 for local installs.',
+        },
+        {
+            displayName: 'Agent ID',
+            name: 'agentId',
+            type: 'string',
+            default: '',
+            required: true,
+            description: 'Logical identity used as the memory owner. Workflows that share an agentId share memory ownership.',
+        },
+        {
+            displayName: 'Admin Password',
+            name: 'adminPassword',
+            type: 'string',
+            typeOptions: { password: true },
+            default: '',
+            required: true,
+            description: "Flair (Harper) admin password. Sensitive: grants read/write to the entire instance. Use Ed25519 per-agent auth (planned) for production with untrusted workflow inputs.",
+        },
+    ];
+    authenticate = {
+        type: 'generic',
+        properties: {
+            headers: {
+                Authorization: "=Basic {{ Buffer.from('admin:' + $credentials.adminPassword).toString('base64') }}",
+            },
+        },
+    };
+    test = {
+        request: {
+            baseURL: '={{ $credentials.baseUrl }}',
+            url: '/Memory',
+        },
+    };
+}
+exports.FlairApi = FlairApi;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/nodes/FlairChatMemory/FlairChatMemory.node.d.ts

@@ -0,0 +1,5 @@
+import { type ISupplyDataFunctions, type INodeType, type INodeTypeDescription, type SupplyData } from "n8n-workflow";
+export declare class FlairChatMemory implements INodeType {
+    description: INodeTypeDescription;
+    supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData>;
+}

package/dist/nodes/FlairChatMemory/FlairChatMemory.node.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlairChatMemory = void 0;
+const memory_1 = require("@langchain/classic/memory");
+const n8n_workflow_1 = require("n8n-workflow");
+const flair_client_1 = require("@tpsdev-ai/flair-client");
+const FlairChatMessageHistory_1 = require("./FlairChatMessageHistory");
+class FlairChatMemory {
+    description = {
+        displayName: "Flair Chat Memory",
+        name: "flairChatMemory",
+        icon: "file:flair.svg",
+        group: ["transform"],
+        version: [1],
+        description: "Store n8n AI Agent chat history in Flair, a portable agent memory backend. The same memory is readable from Claude Code, OpenClaw, and any other Flair client.",
+        defaults: {
+            name: "Flair Chat Memory",
+        },
+        credentials: [
+            {
+                name: "flairApi",
+                required: true,
+            },
+        ],
+        codex: {
+            categories: ["AI"],
+            subcategories: {
+                AI: ["Memory"],
+                Memory: ["Other memories"],
+            },
+            resources: {
+                primaryDocumentation: [
+                    {
+                        url: "https://github.com/tpsdev-ai/flair#n8n",
+                    },
+                ],
+            },
+        },
+        inputs: [],
+        outputs: [n8n_workflow_1.NodeConnectionTypes.AiMemory],
+        outputNames: ["Memory"],
+        properties: [
+            {
+                displayName: "Subject",
+                name: "subject",
+                type: "string",
+                default: '={{ $workflow.name }}',
+                required: true,
+                description: "Flair subject that scopes the chat history. Defaults to the workflow name. Workflows that share a subject share memory.",
+            },
+            {
+                displayName: "Session Sub-Key",
+                name: "sessionKey",
+                type: "string",
+                default: "",
+                description: "Optional sub-scope appended to the subject as `<subject>:<sessionKey>`. Use the n8n execution id (`={{ $execution.id }}`) for per-run isolation, or leave blank to share memory across runs.",
+            },
+            {
+                displayName: "Context Window Length",
+                name: "contextWindowLength",
+                type: "number",
+                default: 10,
+                description: "How many message turns (user + AI = 1 turn) to keep in the buffer window.",
+            },
+        ],
+    };
+    async supplyData(itemIndex) {
+        const credentials = (await this.getCredentials("flairApi"));
+        const subject = this.getNodeParameter("subject", itemIndex);
+        const sessionKey = this.getNodeParameter("sessionKey", itemIndex, "");
+        const k = this.getNodeParameter("contextWindowLength", itemIndex, 10);
+        const composedSubject = sessionKey ? `${subject}:${sessionKey}` : subject;
+        const flair = new flair_client_1.FlairClient({
+            url: credentials.baseUrl,
+            agentId: credentials.agentId,
+            adminUser: "admin",
+            adminPassword: credentials.adminPassword,
+        });
+        const history = new FlairChatMessageHistory_1.FlairChatMessageHistory(flair, composedSubject, k);
+        const memory = new memory_1.BufferWindowMemory({
+            memoryKey: "chat_history",
+            chatHistory: history,
+            returnMessages: true,
+            inputKey: "input",
+            outputKey: "output",
+            k,
+        });
+        return { response: memory };
+    }
+}
+exports.FlairChatMemory = FlairChatMemory;

package/dist/nodes/FlairChatMemory/FlairChatMessageHistory.d.ts

@@ -0,0 +1,34 @@
+import { BaseListChatMessageHistory } from "@langchain/core/chat_history";
+import { type BaseMessage } from "@langchain/core/messages";
+import type { FlairClient } from "@tpsdev-ai/flair-client";
+/**
+ * LangChain `BaseListChatMessageHistory` adapter backed by Flair memory.
+ *
+ * Each chat message is stored as a single Flair memory:
+ *   - content: JSON.stringify(StoredMessage)
+ *   - subject: the composed chat-session subject
+ *   - tags: ["n8n-chat", `role:<type>`]
+ *   - type: "session"
+ *   - durability: "ephemeral"
+ *
+ * `getMessages()` reads memories filtered by subject and reconstructs the
+ * BaseMessage[] in createdAt-ascending order. Order is computed client-side
+ * from the createdAt timestamp because Memory.list does not yet expose a
+ * server-side sort param (tracked as the `order` extension in q3qf §6).
+ *
+ * The `windowK` constructor argument bounds the number of memories fetched
+ * per `getMessages()` call: each turn is two messages (user + AI), so we
+ * fetch up to `windowK * 2` to cover a windowing wrapper that keeps the
+ * last K turns.
+ */
+export declare class FlairChatMessageHistory extends BaseListChatMessageHistory {
+    private readonly client;
+    private readonly subject;
+    private readonly windowK;
+    lc_namespace: string[];
+    constructor(client: FlairClient, subject: string, windowK?: number);
+    getMessages(): Promise<BaseMessage[]>;
+    addMessage(message: BaseMessage): Promise<void>;
+    addMessages(messages: BaseMessage[]): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/nodes/FlairChatMemory/FlairChatMessageHistory.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlairChatMessageHistory = void 0;
+const chat_history_1 = require("@langchain/core/chat_history");
+const messages_1 = require("@langchain/core/messages");
+/**
+ * LangChain `BaseListChatMessageHistory` adapter backed by Flair memory.
+ *
+ * Each chat message is stored as a single Flair memory:
+ *   - content: JSON.stringify(StoredMessage)
+ *   - subject: the composed chat-session subject
+ *   - tags: ["n8n-chat", `role:<type>`]
+ *   - type: "session"
+ *   - durability: "ephemeral"
+ *
+ * `getMessages()` reads memories filtered by subject and reconstructs the
+ * BaseMessage[] in createdAt-ascending order. Order is computed client-side
+ * from the createdAt timestamp because Memory.list does not yet expose a
+ * server-side sort param (tracked as the `order` extension in q3qf §6).
+ *
+ * The `windowK` constructor argument bounds the number of memories fetched
+ * per `getMessages()` call: each turn is two messages (user + AI), so we
+ * fetch up to `windowK * 2` to cover a windowing wrapper that keeps the
+ * last K turns.
+ */
+class FlairChatMessageHistory extends chat_history_1.BaseListChatMessageHistory {
+    client;
+    subject;
+    windowK;
+    lc_namespace = ["n8n-nodes", "flair"];
+    constructor(client, subject, windowK = 10) {
+        super();
+        this.client = client;
+        this.subject = subject;
+        this.windowK = windowK;
+    }
+    async getMessages() {
+        const memories = await this.client.memory.list({
+            subject: this.subject,
+            type: "session",
+            limit: this.windowK * 2,
+        });
+        // Server returns most recent first by default; sort by createdAt asc
+        // so chat history reads chronologically (oldest first).
+        const sorted = [...memories].sort((a, b) => {
+            const ta = a.createdAt ?? "";
+            const tb = b.createdAt ?? "";
+            return ta < tb ? -1 : ta > tb ? 1 : 0;
+        });
+        const stored = sorted
+            .map((m) => {
+            try {
+                return JSON.parse(m.content);
+            }
+            catch {
+                // Memory content isn't a valid StoredMessage envelope — skip
+                // rather than throw. Most likely a memory written by another
+                // surface (CLI, MCP, another agent) sharing the subject.
+                return null;
+            }
+        })
+            .filter((s) => s !== null);
+        return (0, messages_1.mapStoredMessagesToChatMessages)(stored);
+    }
+    async addMessage(message) {
+        const [stored] = (0, messages_1.mapChatMessagesToStoredMessages)([message]);
+        await this.client.memory.write(JSON.stringify(stored), {
+            type: "session",
+            durability: "ephemeral",
+            subject: this.subject,
+            tags: ["n8n-chat", `role:${stored.type}`],
+        });
+    }
+    async addMessages(messages) {
+        // Flair has no batch-write today; fall back to sequential writes.
+        // BaseListChatMessageHistory's default does the same loop — the
+        // override exists so future flair-client batch support can drop in
+        // here without touching consumers.
+        for (const m of messages)
+            await this.addMessage(m);
+    }
+    async clear() {
+        // Best-effort delete of all session memories under this subject.
+        const memories = await this.client.memory.list({
+            subject: this.subject,
+            type: "session",
+            limit: 1000,
+        });
+        for (const m of memories) {
+            try {
+                await this.client.memory.delete(m.id);
+            }
+            catch {
+                // best-effort — keep deleting siblings
+            }
+        }
+    }
+}
+exports.FlairChatMessageHistory = FlairChatMessageHistory;

package/dist/nodes/FlairSearch/FlairSearch.node.d.ts

@@ -0,0 +1,6 @@
+import { type IExecuteFunctions, type INodeExecutionData, type INodeType, type INodeTypeDescription, type ISupplyDataFunctions, type SupplyData } from "n8n-workflow";
+export declare class FlairSearch implements INodeType {
+    description: INodeTypeDescription;
+    supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData>;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/FlairSearch/FlairSearch.node.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlairSearch = void 0;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const n8n_workflow_1 = require("n8n-workflow");
+const flair_client_1 = require("@tpsdev-ai/flair-client");
+function makeClient(credentials) {
+    return new flair_client_1.FlairClient({
+        url: credentials.baseUrl,
+        agentId: credentials.agentId,
+        adminUser: "admin",
+        adminPassword: credentials.adminPassword,
+    });
+}
+async function runSearch(flair, query, limit) {
+    const results = await flair.memory.search(query, { limit });
+    return results.map((r) => ({
+        id: r.id,
+        content: r.content,
+        score: r.score,
+        type: r.type,
+        tags: r.tags,
+        createdAt: r.createdAt,
+    }));
+}
+async function runGetBySubject(flair, subject, limit) {
+    const memories = await flair.memory.list({ subject, limit });
+    return memories.map((m) => ({
+        id: m.id,
+        content: m.content,
+        type: m.type,
+        tags: m.tags,
+        subject: m.subject,
+        createdAt: m.createdAt,
+    }));
+}
+class FlairSearch {
+    description = {
+        displayName: "Flair Search",
+        name: "flairSearch",
+        icon: "file:flair.svg",
+        group: ["transform"],
+        version: [1],
+        description: "Search Flair memory by semantic query or by subject. Use as an AI Agent tool to give the agent access to structured Flair memories.",
+        defaults: {
+            name: "Flair Search",
+        },
+        credentials: [
+            {
+                name: "flairApi",
+                required: true,
+            },
+        ],
+        codex: {
+            categories: ["AI"],
+            subcategories: {
+                AI: ["Tools"],
+                Tools: ["Other Tools"],
+            },
+            resources: {
+                primaryDocumentation: [
+                    {
+                        url: "https://github.com/tpsdev-ai/flair#n8n",
+                    },
+                ],
+            },
+        },
+        inputs: [],
+        outputs: [n8n_workflow_1.NodeConnectionTypes.AiTool],
+        outputNames: ["Tool"],
+        properties: [
+            {
+                displayName: "Operation",
+                name: "operation",
+                type: "options",
+                noDataExpression: true,
+                options: [
+                    {
+                        name: "Semantic Search",
+                        value: "search",
+                        description: "Find memories most semantically similar to a query",
+                    },
+                    {
+                        name: "Get By Subject",
+                        value: "getBySubject",
+                        description: "List memories filtered by subject (the entity/conversation/topic they're about)",
+                    },
+                ],
+                default: "search",
+            },
+            {
+                displayName: "Query",
+                name: "query",
+                type: "string",
+                default: "",
+                required: true,
+                displayOptions: { show: { operation: ["search"] } },
+                description: "The semantic query to search Flair memory for",
+            },
+            {
+                displayName: "Subject",
+                name: "subject",
+                type: "string",
+                default: "",
+                required: true,
+                displayOptions: { show: { operation: ["getBySubject"] } },
+                description: "The subject (entity / topic) to fetch memories for",
+            },
+            {
+                displayName: "Limit",
+                name: "limit",
+                type: "number",
+                default: 5,
+                description: "Maximum number of memories to return",
+            },
+            {
+                displayName: "Get By Tag is not yet available — flair-client.memory.list does not yet expose a tag filter (tracked in q3qf spec §6). Workaround: use Semantic Search and let the model filter results by tags in the response.",
+                name: "tagNotice",
+                type: "notice",
+                default: "",
+            },
+        ],
+    };
+    async supplyData(itemIndex) {
+        const credentials = (await this.getCredentials("flairApi"));
+        const operation = this.getNodeParameter("operation", itemIndex);
+        const limit = this.getNodeParameter("limit", itemIndex, 5);
+        const flair = makeClient(credentials);
+        if (operation === "search") {
+            const tool = new tools_1.DynamicStructuredTool({
+                name: "flair_search",
+                description: "Search Flair memory by semantic similarity. Returns memories ranked by relevance to the query.",
+                schema: zod_1.z.object({
+                    query: zod_1.z
+                        .string()
+                        .describe("The natural-language query to search memory for"),
+                }),
+                func: async ({ query }) => {
+                    const results = await runSearch(flair, query, limit);
+                    return JSON.stringify(results);
+                },
+            });
+            return { response: tool };
+        }
+        // getBySubject — subject is bound at config time so the agent only
+        // chooses to invoke it (not which subject to fetch).
+        const subject = this.getNodeParameter("subject", itemIndex);
+        const tool = new tools_1.DynamicStructuredTool({
+            name: "flair_get_by_subject",
+            description: `Get memories about subject "${subject}" from Flair, ordered by recency.`,
+            schema: zod_1.z.object({}),
+            func: async () => {
+                const results = await runGetBySubject(flair, subject, limit);
+                return JSON.stringify(results);
+            },
+        });
+        return { response: tool };
+    }
+    async execute() {
+        const credentials = (await this.getCredentials("flairApi"));
+        const flair = makeClient(credentials);
+        const inputs = this.getInputData();
+        const out = [];
+        for (let i = 0; i < inputs.length; i++) {
+            const operation = this.getNodeParameter("operation", i);
+            const limit = this.getNodeParameter("limit", i, 5);
+            let results;
+            if (operation === "search") {
+                const query = this.getNodeParameter("query", i);
+                results = await runSearch(flair, query, limit);
+            }
+            else {
+                const subject = this.getNodeParameter("subject", i);
+                results = await runGetBySubject(flair, subject, limit);
+            }
+            out.push({ json: { operation, results }, pairedItem: { item: i } });
+        }
+        return [out];
+    }
+}
+exports.FlairSearch = FlairSearch;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tpsdev-ai/n8n-nodes-flair",
+  "version": "0.8.0",
+  "description": "n8n community node — use Flair as your AI Agent's memory backend. Includes FlairChatMemory (Memory port) and FlairSearch (Tool port).",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:assets",
+    "build:assets": "node -e \"require('fs').cpSync('src/credentials','dist/credentials',{recursive:true,filter:p=>!p.endsWith('.ts')});require('fs').cpSync('src/nodes','dist/nodes',{recursive:true,filter:p=>!p.endsWith('.ts')})\"",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/FlairApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/FlairChatMemory/FlairChatMemory.node.js",
+      "dist/nodes/FlairSearch/FlairSearch.node.js"
+    ]
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tpsdev-ai/flair.git",
+    "directory": "packages/n8n-nodes-flair"
+  },
+  "homepage": "https://tps.dev/#flair",
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "flair",
+    "ai",
+    "agent",
+    "memory",
+    "langchain"
+  ],
+  "dependencies": {
+    "@tpsdev-ai/flair-client": "0.8.0",
+    "zod": "3.25.76"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*",
+    "@langchain/core": "*",
+    "@langchain/classic": "*"
+  },
+  "devDependencies": {
+    "n8n-workflow": "1.119.0",
+    "@langchain/core": "1.1.44",
+    "@langchain/classic": "1.0.32",
+    "typescript": "5.9.3"
+  }
+}