@tpsdev-ai/flair-client 0.7.0 → 0.8.1

package/dist/client.d.ts

@@ -16,6 +16,7 @@ export declare class FlairClient {
     private privateKey;
     private keyResolved;
     private keyPath;
+    private rawPrivateKey;
     private timeoutMs;
     private basicAuth;
     constructor(config: FlairClientConfig);
@@ -61,11 +62,26 @@ declare class MemoryApi {
     }): Promise<SearchResult[]>;
     /** Get a memory by ID. */
     get(id: string): Promise<Memory | null>;
-    /** List recent memories. */
+    /**
+     * List recent memories. All filters combine with AND.
+     *
+     * Uses Harper's `POST /Memory/search_by_conditions` endpoint with an
+     * explicit conditions array. The Memory.search() override injects the
+     * agentId scoping condition.
+     *
+     * Note: `order` is applied client-side after retrieval. Harper's
+     * search_by_conditions does not accept a sort/order field in the body.
+     */
     list(opts?: {
+        tags?: string[];
         limit?: number;
         type?: MemoryType;
         durability?: Durability;
+        /** Filter by subject (entity the memory is about). Indexed; efficient. */
+        subject?: string;
+        /** Chronological ordering applied client-side after retrieval.
+         *  Server-side sort is not available via search_by_conditions. */
+        order?: "createdAt-asc" | "createdAt-desc";
     }): Promise<Memory[]>;
     /** Delete a memory. */
     delete(id: string): Promise<void>;

package/dist/client.js

@@ -7,6 +7,7 @@
  *   const results = await flair.memory.search('that thing')
  *   const ctx = await flair.bootstrap({ maxTokens: 4000 })
  */
+import { createPrivateKey } from "node:crypto";
 import { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
 const DEFAULT_URL = "http://localhost:19926";
 const DEFAULT_TIMEOUT = 30_000;
@@ -18,12 +19,16 @@ export class FlairClient {
     privateKey = null;
     keyResolved = false;
     keyPath;
+    rawPrivateKey;
     timeoutMs;
     basicAuth = null;
     constructor(config) {
         this.url = (config.url ?? process.env.FLAIR_URL ?? DEFAULT_URL).replace(/\/$/, "");
         this.agentId = config.agentId || process.env.FLAIR_AGENT_ID || "";
         this.keyPath = config.keyPath;
+        if (config.privateKey !== undefined) {
+            this.rawPrivateKey = config.privateKey;
+        }
         this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT;
         // Basic auth fallback for standalone deployments without Ed25519 keys
         const adminUser = config.adminUser ?? process.env.FLAIR_ADMIN_USER;
@@ -38,6 +43,16 @@ export class FlairClient {
         if (this.keyResolved)
             return this.privateKey;
         this.keyResolved = true;
+        // In-memory key takes priority over file-based resolution.
+        if (this.rawPrivateKey) {
+            if (typeof this.rawPrivateKey === "string") {
+                this.privateKey = createPrivateKey(this.rawPrivateKey);
+            }
+            else {
+                this.privateKey = this.rawPrivateKey;
+            }
+            return this.privateKey;
+        }
         const path = resolveKeyPath(this.agentId, this.keyPath);
         if (path) {
             // Key file exists — failure to parse is a hard error.
@@ -101,10 +116,11 @@ class MemoryApi {
             // dedup checks inflate scores above the threshold.
             const existing = await this.search(content, { limit: 1, minScore: threshold, scoring: "raw" });
             if (existing.length > 0) {
-                // Return the existing memory instead of creating a duplicate
+                // Return the existing memory instead of creating a duplicate.
+                // Flag deduped so callers know this write was suppressed.
                 const match = await this.get(existing[0].id);
                 if (match)
-                    return match;
+                    return { ...match, deduped: true };
             }
         }
         const id = opts.id ?? `${this.client.agentId}-${crypto.randomUUID()}`;
@@ -149,17 +165,49 @@ class MemoryApi {
             throw e;
         }
     }
-    /** List recent memories. */
+    /**
+     * List recent memories. All filters combine with AND.
+     *
+     * Uses Harper's `POST /Memory/search_by_conditions` endpoint with an
+     * explicit conditions array. The Memory.search() override injects the
+     * agentId scoping condition.
+     *
+     * Note: `order` is applied client-side after retrieval. Harper's
+     * search_by_conditions does not accept a sort/order field in the body.
+     */
     async list(opts = {}) {
-        const params = new URLSearchParams();
-        params.set("agentId", this.client.agentId);
+        // Build conditions array — agentId is always scoped
+        const conditions = [
+            { search_attribute: "agentId", search_type: "equals", search_value: this.client.agentId },
+        ];
+        if (opts.subject) {
+            conditions.push({ search_attribute: "subject", search_type: "equals", search_value: opts.subject });
+        }
+        for (const tag of opts.tags ?? []) {
+            conditions.push({ search_attribute: "tags", search_type: "contains", search_value: tag });
+        }
+        if (opts.type) {
+            conditions.push({ search_attribute: "type", search_type: "equals", search_value: opts.type });
+        }
+        if (opts.durability) {
+            conditions.push({ search_attribute: "durability", search_type: "equals", search_value: opts.durability });
+        }
+        const body = {
+            operator: "and",
+            conditions,
+            get_attributes: ["*"],
+        };
         if (opts.limit)
-            params.set("limit", String(opts.limit));
-        if (opts.type)
-            params.set("type", opts.type);
-        if (opts.durability)
-            params.set("durability", opts.durability);
-        return this.client.request("GET", `/Memory?${params}`);
+            body.limit = opts.limit;
+        const result = await this.client.request("POST", "/Memory/search_by_conditions", body);
+        // search_by_conditions returns either an array or { results: [...] }
+        const memories = Array.isArray(result) ? result : (result?.results ?? []);
+        // Client-side sort (Harper's search_by_conditions does not accept sort in body)
+        if (opts.order) {
+            const dir = opts.order === "createdAt-desc" ? -1 : 1;
+            memories.sort((a, b) => dir * (a.createdAt > b.createdAt ? 1 : a.createdAt < b.createdAt ? -1 : 0));
+        }
+        return memories;
     }
     /** Delete a memory. */
     async delete(id) {

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import type { KeyObject } from "node:crypto";
+export type { KeyObject };
 /** Memory durability levels. */
 export type Durability = "permanent" | "persistent" | "standard" | "ephemeral";
 /** Memory type classification. */
@@ -13,6 +15,9 @@ export interface Memory {
     subject?: string;
     createdAt: string;
     updatedAt?: string;
+    /** Set to true when write() returned an existing near-duplicate instead of
+     *  creating a new entry. Omitted/undefined for new writes. */
+    deduped?: boolean;
 }
 /** A soul entry (persistent personality/values). */
 export interface SoulEntry {
@@ -47,6 +52,9 @@ export interface FlairClientConfig {
     agentId?: string;
     /** Path to Ed25519 private key file. Auto-resolved if omitted. */
     keyPath?: string;
+    /** In-memory Ed25519 private key (PEM string or pre-loaded KeyObject).
+     *  Bypasses keyPath/file resolution. Wins over keyPath when both are supplied. */
+    privateKey?: string | KeyObject;
     /** Request timeout in ms. Default: 10000 */
     timeoutMs?: number;
     /** Admin username for Basic auth fallback (standalone deployments). Falls back to FLAIR_ADMIN_USER env var. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-client",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Lightweight client for Flair — identity, memory, and soul for AI agents. Zero heavy dependencies.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tpsdev-ai/flair.git",
+    "url": "git+https://github.com/tpsdev-ai/flair.git",
     "directory": "packages/flair-client"
   },
   "homepage": "https://tps.dev/#flair",