@tpsdev-ai/flair-client 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# @tpsdev-ai/flair-client
+
+Lightweight client for [Flair](https://tps.dev/#flair) — identity, memory, and soul for AI agents.
+
+Zero heavy dependencies. Just Ed25519 auth + HTTP. Works with any Flair instance, local or remote.
+
+## Install
+
+```bash
+npm install @tpsdev-ai/flair-client
+```
+
+## Quick Start
+
+```ts
+import { FlairClient } from '@tpsdev-ai/flair-client'
+
+const flair = new FlairClient({
+  url: 'http://localhost:9926',   // or remote: https://flair.example.com
+  agentId: 'my-agent',
+  // keyPath auto-resolved from ~/.flair/keys/my-agent.key
+})
+
+// Write a memory
+await flair.memory.write('Harper v5 sandbox blocks bare imports')
+
+// Search by meaning
+const results = await flair.memory.search('native module loading issues')
+// → [{ content: 'Harper v5 sandbox blocks bare imports', score: 0.72, ... }]
+
+// Cold-start bootstrap (soul + recent memories)
+const ctx = await flair.bootstrap({ maxTokens: 4000 })
+console.log(ctx.context) // formatted context block
+```
+
+## Memory API
+
+```ts
+// Write with options
+await flair.memory.write('deploy procedure changed', {
+  type: 'decision',
+  durability: 'persistent',
+  tags: ['ops', 'deploy'],
+})
+
+// Get by ID
+const mem = await flair.memory.get('my-agent-1234567890')
+
+// List recent
+const recent = await flair.memory.list({ limit: 10 })
+
+// Delete
+await flair.memory.delete('my-agent-1234567890')
+```
+
+## Soul API
+
+```ts
+// Set personality/values
+await flair.soul.set('role', 'Security reviewer, meticulous and skeptical')
+await flair.soul.set('tone', 'Direct, technical, no fluff')
+
+// Read
+const role = await flair.soul.get('role')
+
+// List all
+const entries = await flair.soul.list()
+```
+
+## Auth
+
+Flair uses Ed25519 signatures. The client auto-discovers your key from:
+
+1. `keyPath` option (explicit)
+2. `FLAIR_KEY_DIR` env + `{agentId}.key`
+3. `~/.flair/keys/{agentId}.key`
+4. `~/.tps/secrets/flair/{agentId}-priv.key`
+
+Generate a key with the Flair CLI:
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init && flair agent add my-agent
+```
+
+## Use with Claude Code
+
+Add to your `CLAUDE.md`:
+
+```markdown
+## Memory (Flair)
+You have persistent memory. Use it.
+- Bootstrap on start: `npx @tpsdev-ai/flair-client bootstrap --agent $AGENT_ID`
+- Store lessons: `npx @tpsdev-ai/flair-client write --agent $AGENT_ID "what you learned"`
+- Search: `npx @tpsdev-ai/flair-client search --agent $AGENT_ID "your query"`
+```
+
+Or use the Flair CLI directly:
+
+```markdown
+## Memory (Flair)
+- `flair memory search --agent my-agent -q "your query"`
+- `flair memory add --agent my-agent --content "what to remember"`
+- `flair memory list --agent my-agent --limit 20`
+```
+
+## Configuration
+
+| Option | Env | Default | Description |
+|--------|-----|---------|-------------|
+| `url` | `FLAIR_URL` | `http://localhost:9926` | Flair server URL |
+| `agentId` | `FLAIR_AGENT_ID` | — | Agent identifier |
+| `keyPath` | `FLAIR_KEY_DIR` | auto-resolved | Private key path |
+| `timeoutMs` | — | `10000` | Request timeout |
+
+## License
+
+[Apache 2.0](../../LICENSE)

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ed25519 request signing for Flair.
+ *
+ * Signs requests with: agentId:timestamp:nonce:METHOD:/path
+ * Produces: TPS-Ed25519 agentId:timestamp:nonce:base64(signature)
+ */
+import { type KeyObject } from "node:crypto";
+/** Resolve an Ed25519 private key from a file (base64 PKCS8 DER or raw 32-byte seed). */
+export declare function loadPrivateKey(path: string): KeyObject;
+/** Find the agent's private key file from standard locations. */
+export declare function resolveKeyPath(agentId: string, keyPath?: string): string | null;
+/** Build an Authorization header for a Flair request. */
+export declare function signRequest(agentId: string, privateKey: KeyObject, method: string, path: string): string;

package/dist/auth.js

@@ -0,0 +1,42 @@
+/**
+ * Ed25519 request signing for Flair.
+ *
+ * Signs requests with: agentId:timestamp:nonce:METHOD:/path
+ * Produces: TPS-Ed25519 agentId:timestamp:nonce:base64(signature)
+ */
+import { randomUUID, sign as ed25519Sign, createPrivateKey } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+/** Resolve an Ed25519 private key from a file (base64 PKCS8 DER or raw 32-byte seed). */
+export function loadPrivateKey(path) {
+    const raw = readFileSync(path);
+    // Try as base64-encoded PKCS8 DER first
+    const decoded = raw.length === 32 ? raw : Buffer.from(raw.toString("utf-8").trim(), "base64");
+    const der = decoded.length === 32
+        ? Buffer.concat([PKCS8_ED25519_PREFIX, decoded])
+        : decoded;
+    return createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+}
+/** Find the agent's private key file from standard locations. */
+export function resolveKeyPath(agentId, keyPath) {
+    if (keyPath) {
+        const resolved = resolve(keyPath.replace(/^~/, homedir()));
+        return existsSync(resolved) ? resolved : null;
+    }
+    const candidates = [
+        process.env.FLAIR_KEY_DIR ? resolve(process.env.FLAIR_KEY_DIR, `${agentId}.key`) : null,
+        resolve(homedir(), ".flair", "keys", `${agentId}.key`),
+        resolve(homedir(), ".tps", "secrets", "flair", `${agentId}-priv.key`),
+    ].filter(Boolean);
+    return candidates.find(existsSync) ?? null;
+}
+/** Build an Authorization header for a Flair request. */
+export function signRequest(agentId, privateKey, method, path) {
+    const ts = Date.now().toString();
+    const nonce = randomUUID();
+    const payload = `${agentId}:${ts}:${nonce}:${method}:${path}`;
+    const sig = ed25519Sign(null, Buffer.from(payload), privateKey);
+    return `TPS-Ed25519 ${agentId}:${ts}:${nonce}:${sig.toString("base64")}`;
+}

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Flair client — lightweight, zero-dep HTTP client for Flair.
+ *
+ * Usage:
+ *   const flair = new FlairClient({ agentId: 'my-agent' })
+ *   await flair.memory.write('learned something')
+ *   const results = await flair.memory.search('that thing')
+ *   const ctx = await flair.bootstrap({ maxTokens: 4000 })
+ */
+import type { FlairClientConfig, Memory, MemoryType, Durability, SoulEntry, SearchResult, BootstrapResult } from "./types.js";
+export declare class FlairClient {
+    readonly url: string;
+    readonly agentId: string;
+    readonly memory: MemoryApi;
+    readonly soul: SoulApi;
+    private privateKey;
+    private keyResolved;
+    private keyPath;
+    private timeoutMs;
+    constructor(config: FlairClientConfig);
+    private resolveKey;
+    /** Make an authenticated request to Flair. */
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    /** Cold-start bootstrap — get soul + recent memories as a formatted context block. */
+    bootstrap(opts?: {
+        maxTokens?: number;
+    }): Promise<BootstrapResult>;
+    /** Health check. */
+    health(): Promise<{
+        status: string;
+    }>;
+}
+declare class MemoryApi {
+    private client;
+    constructor(client: FlairClient);
+    /** Write a memory. */
+    write(content: string, opts?: {
+        id?: string;
+        type?: MemoryType;
+        durability?: Durability;
+        tags?: string[];
+        subject?: string;
+    }): Promise<Memory>;
+    /** Search memories by meaning. */
+    search(query: string, opts?: {
+        limit?: number;
+    }): Promise<SearchResult[]>;
+    /** Get a memory by ID. */
+    get(id: string): Promise<Memory | null>;
+    /** List recent memories. */
+    list(opts?: {
+        limit?: number;
+        type?: MemoryType;
+        durability?: Durability;
+    }): Promise<Memory[]>;
+    /** Delete a memory. */
+    delete(id: string): Promise<void>;
+}
+declare class SoulApi {
+    private client;
+    constructor(client: FlairClient);
+    /** Set a soul entry (key-value personality/values). */
+    set(key: string, value: string): Promise<SoulEntry>;
+    /** Get a soul entry. */
+    get(key: string): Promise<SoulEntry | null>;
+    /** List all soul entries. */
+    list(): Promise<SoulEntry[]>;
+}
+export declare class FlairError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    readonly body: string;
+    constructor(method: string, path: string, status: number, body: string);
+}
+export {};

package/dist/client.js

@@ -0,0 +1,184 @@
+/**
+ * Flair client — lightweight, zero-dep HTTP client for Flair.
+ *
+ * Usage:
+ *   const flair = new FlairClient({ agentId: 'my-agent' })
+ *   await flair.memory.write('learned something')
+ *   const results = await flair.memory.search('that thing')
+ *   const ctx = await flair.bootstrap({ maxTokens: 4000 })
+ */
+import { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
+const DEFAULT_URL = "http://localhost:9926";
+const DEFAULT_TIMEOUT = 10_000;
+export class FlairClient {
+    url;
+    agentId;
+    memory;
+    soul;
+    privateKey = null;
+    keyResolved = false;
+    keyPath;
+    timeoutMs;
+    constructor(config) {
+        this.url = (config.url ?? DEFAULT_URL).replace(/\/$/, "");
+        this.agentId = config.agentId;
+        this.keyPath = config.keyPath;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT;
+        this.memory = new MemoryApi(this);
+        this.soul = new SoulApi(this);
+    }
+    resolveKey() {
+        if (this.keyResolved)
+            return this.privateKey;
+        this.keyResolved = true;
+        const path = resolveKeyPath(this.agentId, this.keyPath);
+        if (path) {
+            // Key file exists — failure to parse is a hard error.
+            // Silent fallback to unauthenticated would be a security risk.
+            this.privateKey = loadPrivateKey(path);
+        }
+        return this.privateKey;
+    }
+    /** Make an authenticated request to Flair. */
+    async request(method, path, body) {
+        const headers = { "Content-Type": "application/json" };
+        const key = this.resolveKey();
+        if (key) {
+            headers["Authorization"] = signRequest(this.agentId, key, method, path);
+        }
+        const res = await fetch(`${this.url}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new FlairError(method, path, res.status, text.slice(0, 500));
+        }
+        const text = await res.text();
+        return text ? JSON.parse(text) : {};
+    }
+    /** Cold-start bootstrap — get soul + recent memories as a formatted context block. */
+    async bootstrap(opts = {}) {
+        return this.request("POST", "/BootstrapMemories", {
+            agentId: this.agentId,
+            maxTokens: opts.maxTokens ?? 4000,
+        });
+    }
+    /** Health check. */
+    async health() {
+        return this.request("GET", "/Health");
+    }
+}
+// ─── Memory API ─────────────────────────────────────────────────────────────
+class MemoryApi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Write a memory. */
+    async write(content, opts = {}) {
+        const id = opts.id ?? `${this.client.agentId}-${Date.now()}`;
+        return this.client.request("PUT", `/Memory/${id}`, {
+            id,
+            agentId: this.client.agentId,
+            content,
+            type: opts.type ?? "session",
+            durability: opts.durability ?? "standard",
+            tags: opts.tags ?? [],
+            subject: opts.subject,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    /** Search memories by meaning. */
+    async search(query, opts = {}) {
+        const result = await this.client.request("POST", "/SemanticSearch", { agentId: this.client.agentId, q: query, limit: opts.limit ?? 5 });
+        return (result.results ?? []).map((r) => ({
+            id: r.id ?? r.memory?.id ?? "",
+            content: r.content ?? r.memory?.content ?? "",
+            score: r.score ?? r.similarity ?? 0,
+            type: r.type ?? r.memory?.type,
+            durability: r.durability ?? r.memory?.durability,
+            tags: r.tags ?? r.memory?.tags,
+            createdAt: r.createdAt ?? r.memory?.createdAt,
+        }));
+    }
+    /** Get a memory by ID. */
+    async get(id) {
+        try {
+            return await this.client.request("GET", `/Memory/${id}`);
+        }
+        catch (e) {
+            if (e instanceof FlairError && e.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** List recent memories. */
+    async list(opts = {}) {
+        const params = new URLSearchParams();
+        params.set("agentId", this.client.agentId);
+        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}`);
+    }
+    /** Delete a memory. */
+    async delete(id) {
+        await this.client.request("DELETE", `/Memory/${id}`);
+    }
+}
+// ─── Soul API ───────────────────────────────────────────────────────────────
+class SoulApi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Set a soul entry (key-value personality/values). */
+    async set(key, value) {
+        const id = `${this.client.agentId}:${key}`;
+        return this.client.request("PUT", `/Soul/${encodeURIComponent(id)}`, {
+            id,
+            agentId: this.client.agentId,
+            key,
+            value,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    /** Get a soul entry. */
+    async get(key) {
+        const id = `${this.client.agentId}:${key}`;
+        try {
+            return await this.client.request("GET", `/Soul/${encodeURIComponent(id)}`);
+        }
+        catch (e) {
+            if (e instanceof FlairError && e.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** List all soul entries. */
+    async list() {
+        const params = new URLSearchParams({ agentId: this.client.agentId });
+        return this.client.request("GET", `/Soul?${params}`);
+    }
+}
+// ─── Error ──────────────────────────────────────────────────────────────────
+export class FlairError extends Error {
+    method;
+    path;
+    status;
+    body;
+    constructor(method, path, status, body) {
+        super(`Flair ${method} ${path} → ${status}: ${body}`);
+        this.method = method;
+        this.path = path;
+        this.status = status;
+        this.body = body;
+        this.name = "FlairError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FlairClient, FlairError } from "./client.js";
+export { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
+export type { FlairClientConfig, Memory, MemoryType, Durability, SoulEntry, SearchResult, BootstrapResult, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { FlairClient, FlairError } from "./client.js";
+export { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/** Memory durability levels. */
+export type Durability = "permanent" | "persistent" | "standard" | "ephemeral";
+/** Memory type classification. */
+export type MemoryType = "session" | "lesson" | "decision" | "preference" | "fact" | "goal";
+/** A memory record. */
+export interface Memory {
+    id: string;
+    agentId: string;
+    content: string;
+    type: MemoryType;
+    durability: Durability;
+    tags: string[];
+    subject?: string;
+    createdAt: string;
+    updatedAt?: string;
+}
+/** A soul entry (persistent personality/values). */
+export interface SoulEntry {
+    id: string;
+    agentId: string;
+    key: string;
+    value: string;
+    createdAt: string;
+}
+/** Semantic search result. */
+export interface SearchResult {
+    id: string;
+    content: string;
+    score: number;
+    type?: MemoryType;
+    durability?: Durability;
+    tags?: string[];
+    createdAt?: string;
+}
+/** Bootstrap response — formatted context block. */
+export interface BootstrapResult {
+    context: string;
+    memoryCount: number;
+    soulCount: number;
+    tokenEstimate: number;
+}
+/** Client configuration. */
+export interface FlairClientConfig {
+    /** Flair server URL. Default: http://localhost:9926 */
+    url?: string;
+    /** Agent ID for authentication and data scoping. */
+    agentId: string;
+    /** Path to Ed25519 private key file. Auto-resolved if omitted. */
+    keyPath?: string;
+    /** Request timeout in ms. Default: 10000 */
+    timeoutMs?: number;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tpsdev-ai/flair-client",
+  "version": "0.1.0",
+  "description": "Lightweight client for Flair — identity, memory, and soul for AI agents. Zero heavy dependencies.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tpsdev-ai/flair.git",
+    "directory": "packages/flair-client"
+  },
+  "homepage": "https://tps.dev/#flair",
+  "keywords": [
+    "flair",
+    "ai",
+    "agent",
+    "memory",
+    "identity",
+    "client",
+    "ed25519"
+  ],
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}