@tpsdev-ai/flair 0.12.0 → 0.13.0

package/dist/cli.js

@@ -510,35 +510,11 @@ export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, ad
         throw new Error(`Operations API insert failed (${res.status}): ${text}`);
     }
 }
-// Seed an agent record via the Harper REST API.
-// Uses localhost and the given HTTP port.
-export async function seedAgentViaRestApi(httpPort, agentId, pubKeyB64url, adminPass) {
-    const baseUrl = `http://127.0.0.1:${httpPort}`;
-    const body = {
-        operation: "insert",
-        database: "flair",
-        table: "Agent",
-        records: [{ id: agentId, name: agentId, publicKey: pubKeyB64url, createdAt: new Date().toISOString() }],
-    };
-    // Only send Authorization header if adminPass is provided.
-    // Matches the auth pattern in api() which respects authorizeLocal=true.
-    const headers = { "Content-Type": "application/json" };
-    if (adminPass) {
-        headers.Authorization = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
-    }
-    const res = await fetch(`${baseUrl}/Agent`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(10_000),
-    });
-    if (!res.ok) {
-        const text = await res.text().catch(() => "");
-        if (res.status === 409 || text.includes("duplicate") || text.includes("already exists"))
-            return;
-        throw new Error(`REST API insert failed (${res.status}): ${text}`);
-    }
-}
+// NOTE: agent records are seeded exclusively via the Harper operations API
+// (seedAgentViaOpsApi above). A former seedAgentViaRestApi() helper POSTed the
+// ops-insert body to the REST root, which Harper 405s as a collection POST to
+// /Agent (the Agent table resource has no POST handler). It was removed in the
+// #499 fix; do not reintroduce a REST-root insert path.
 // ─── FederationInstance seed via ops API ──────────────────────────────────────
 //
 // Remote init writes FederationInstance through the ops API (Basic auth with
@@ -1980,8 +1956,21 @@ program
         writeConfig(httpPort);
     }
     else {
-        // Flair already initialized — resolve admin pass from env or running instance
+        // Flair already initialized — resolve admin pass from env, falling back to
+        // the persisted ~/.flair/admin-pass written at first install. Agent
+        // seeding now goes through the ops API (#499), which always requires Basic
+        // admin auth (it does NOT honor authorizeLocal), so a re-run of
+        // `flair install --agent <new-id>` against an already-initialized local
+        // Flair needs a real pass even when no env var is set.
         adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
+        if (!adminPass) {
+            try {
+                const persisted = join(homedir(), ".flair", "admin-pass");
+                if (existsSync(persisted))
+                    adminPass = readFileSync(persisted, "utf-8").trim();
+            }
+            catch { /* fall through with empty pass */ }
+        }
     }
     const httpUrl = `http://127.0.0.1:${httpPort}`;
     // ── Step 2: Detect MCP clients ──
@@ -2040,17 +2029,16 @@ program
         writeFileSync(pubPath, Buffer.from(kp.publicKey));
         const pubKeyB64url = b64url(kp.publicKey);
         console.log(`Keypair written: ${privPath} ✓`);
-        // Seed agent - use REST API for local Harper, Ops API only when --ops-target is specified
-        if (opts.opsTarget) {
-            // Remote Harper via explicit ops target
-            console.log(`Seeding agent '${agentId}' via operations API (--ops-target)...`);
-            await seedAgentViaOpsApi(opts.opsTarget, agentId, pubKeyB64url, adminUser, adminPass);
-        }
-        else {
-            // Local Harper - use REST API
-            console.log(`Seeding agent '${agentId}' via REST API...`);
-            await seedAgentViaRestApi(httpPort, agentId, pubKeyB64url, adminPass);
-        }
+        // Seed agent via the Harper operations API. The Agent table is a REST
+        // resource without a POST handler, so the insert body must go to the ops
+        // API (POST <opsUrl>/ with {operation:"insert",...}), NOT the REST root
+        // (which 405s the body as a collection POST to /Agent). This is the same
+        // path `flair agent add` uses. (#499)
+        const seedOpsTarget = opts.opsTarget ?? opsPort;
+        console.log(opts.opsTarget
+            ? `Seeding agent '${agentId}' via operations API (--ops-target)...`
+            : `Seeding agent '${agentId}' via operations API...`);
+        await seedAgentViaOpsApi(seedOpsTarget, agentId, pubKeyB64url, adminUser, adminPass);
         console.log(`Agent '${agentId}' registered ✓`);
     }
     // ── Step 4: Wire MCP clients ──
@@ -2209,10 +2197,16 @@ agent
     if (adminPass) {
         const opsPort = resolveOpsPort(opts);
         const auth = Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64");
+        // List every Agent without null-scanning the primary key. A
+        // `starts_with ""` on `id` makes Harper search the index for nulls, which
+        // the bundled Harper (5.0.21) rejects with "id is not indexed for nulls".
+        // Use `createdAt > 1970-01-01` as the total "select all" predicate: every
+        // Agent row has a non-null createdAt (schema: createdAt: String!), and its
+        // index is built — same pattern as the `flair reembed` Memory scan. (#500)
         const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: `Basic ${auth}` },
-            body: JSON.stringify({ operation: "search_by_value", schema: "flair", table: "Agent", search_attribute: "id", search_type: "starts_with", search_value: "", get_attributes: ["id", "name", "createdAt"] }),
+            body: JSON.stringify({ operation: "search_by_conditions", schema: "flair", table: "Agent", operator: "and", conditions: [{ search_attribute: "createdAt", search_type: "greater_than", search_value: "1970-01-01" }], get_attributes: ["id", "name", "createdAt"] }),
         });
         if (!res.ok) {
             const text = await res.text().catch(() => "");
@@ -4198,7 +4192,7 @@ rem
         console.log(result.prompt ?? "(no prompt returned)");
         console.log("--- End Prompt ---\n");
         console.log("Feed the prompt above to your LLM, then write insights back with:");
-        console.log("  flair memory add --agent <id> --content <insight> --durability persistent");
+        console.log("  flair memory add --agent <id> --content <insight> --durability persistent --derived-from <source-ids>");
     }
     catch (err) {
         console.error(`Error: ${err.message}`);
@@ -7010,6 +7004,7 @@ memory.command("add [content]").requiredOption("--agent <id>")
     .option("--durability <d>", "standard").option("--tags <csv>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content; ops-wkoh)")
     .option("--subject <text>", "one-line title / entity this memory is about")
+    .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
     .action(async (contentArg, opts) => {
     const content = contentArg ?? opts.content;
     if (!content) {
@@ -7026,6 +7021,9 @@ memory.command("add [content]").requiredOption("--agent <id>")
         body.summary = opts.summary;
     if (opts.subject)
         body.subject = opts.subject;
+    if (opts.derivedFrom) {
+        body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
+    }
     const out = await api("PUT", `/Memory/${memId}`, body);
     console.log(JSON.stringify(out, null, 2));
 });
@@ -7649,12 +7647,17 @@ soul.command("set")
     .option("--durability <d>", "permanent")
     .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const out = await api("POST", "/Soul", {
-        id: `${opts.agent}:${opts.key}`,
+    // PUT /Soul/{agentId:key} (upsert by id), matching flair-client's soul.set().
+    // The Soul table resource has no POST handler, so a collection POST /Soul
+    // 405s; the record must be written by its primary key. (#498)
+    const id = `${opts.agent}:${opts.key}`;
+    const out = await api("PUT", `/Soul/${encodeURIComponent(id)}`, {
+        id,
         agentId: opts.agent,
         key: opts.key,
         value: opts.value,
         durability: opts.durability,
+        createdAt: new Date().toISOString(),
     });
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {

package/dist/resources/MemoryConsolidate.js

@@ -17,44 +17,7 @@
  */
 import { Resource, databases } from "@harperfast/harper";
 import { isAdmin, allowVerified } from "./agent-auth.js";
-function parseDuration(s) {
-    const m = s.match(/^(\d+)([dhm])$/);
-    if (!m)
-        return 30 * 86400_000;
-    const n = Number(m[1]);
-    if (m[2] === "d")
-        return n * 86400_000;
-    if (m[2] === "h")
-        return n * 3600_000;
-    if (m[2] === "m")
-        return n * 60_000;
-    return 30 * 86400_000;
-}
-function evaluate(record, now, olderThanMs) {
-    const ageMs = record.createdAt ? now - new Date(record.createdAt).getTime() : 0;
-    const count = record.retrievalCount ?? 0;
-    const daysSinceRetrieved = record.lastRetrieved
-        ? (now - new Date(record.lastRetrieved).getTime()) / 86400_000
-        : Infinity;
-    const { embedding, ...memory } = record;
-    // Promote: high retrieval + persistent durability
-    if (record.durability === "persistent" && count >= 5) {
-        return { memory, suggestion: "promote", reason: `Retrieved ${count} times — strong promotion candidate for permanent` };
-    }
-    // Promote: standard → persistent if retrieved frequently
-    if (record.durability === "standard" && count >= 3 && ageMs > 7 * 86400_000) {
-        return { memory, suggestion: "promote", reason: `Retrieved ${count} times over ${Math.round(ageMs / 86400_000)} days — worth persisting` };
-    }
-    // Archive: old + never retrieved
-    if (daysSinceRetrieved > 30 && count === 0 && ageMs > olderThanMs) {
-        return { memory, suggestion: "archive", reason: `Never retrieved, ${Math.round(ageMs / 86400_000)} days old` };
-    }
-    // Archive: last retrieved > 60 days
-    if (daysSinceRetrieved > 60 && count < 2) {
-        return { memory, suggestion: "archive", reason: `Not retrieved in ${Math.round(daysSinceRetrieved)} days (only ${count} total retrievals)` };
-    }
-    return { memory, suggestion: "keep", reason: `Retrieved ${count} times, ${Math.round(daysSinceRetrieved)} days since last retrieval` };
-}
+import { evaluate, parseDuration } from "./memory-consolidate-lib.js";
 export class ConsolidateMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may consolidate; the isAdmin checks in

package/dist/resources/SemanticSearch.js

@@ -4,40 +4,10 @@ import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { wrapUntrusted } from "./content-safety.js";
-// ─── Temporal Decay + Relevance Scoring ─────────────────────────────────────
-const DURABILITY_WEIGHTS = {
-    permanent: 1.0,
-    persistent: 0.9,
-    standard: 0.7,
-    ephemeral: 0.4,
-};
-// Half-life in days for exponential decay per durability level
-const DECAY_HALF_LIFE_DAYS = {
-    permanent: Infinity, // never decays
-    persistent: 90,
-    standard: 30,
-    ephemeral: 7,
-};
-function recencyFactor(createdAt, durability) {
-    const halfLife = DECAY_HALF_LIFE_DAYS[durability] ?? 30;
-    if (halfLife === Infinity)
-        return 1.0;
-    const ageDays = (Date.now() - Date.parse(createdAt)) / (1000 * 60 * 60 * 24);
-    const lambda = Math.LN2 / halfLife;
-    return Math.exp(-lambda * ageDays);
-}
-function retrievalBoost(retrievalCount) {
-    if (!retrievalCount || retrievalCount <= 0)
-        return 1.0;
-    return 1.0 + 0.1 * Math.log2(retrievalCount); // gentle boost: 10 retrievals → ~1.33x
-}
-function compositeScore(semanticScore, record) {
-    const durability = record.durability ?? "standard";
-    const dWeight = DURABILITY_WEIGHTS[durability] ?? 0.7;
-    const rFactor = record.createdAt ? recencyFactor(record.createdAt, durability) : 1.0;
-    const rBoost = retrievalBoost(record.retrievalCount ?? 0);
-    return semanticScore * dWeight * rFactor * rBoost;
-}
+// Temporal decay + relevance scoring (incl. the OPS-AYGD retrievalBoost cap +
+// relevance floor) lives in ./scoring.ts — a Harper-free module so it can be
+// unit-tested directly (see test/unit/temporal-scoring.test.ts).
+import { compositeScore } from "./scoring.js";
 // Convert HNSW cosine distance (1 - similarity) to similarity score
 function distanceToSimilarity(distance) {
     return 1 - distance;

package/dist/resources/memory-consolidate-lib.js

@@ -0,0 +1,72 @@
+// ─── Memory Consolidation — pure evaluation logic ───────────────────────────
+// Pure helpers extracted from MemoryConsolidate.ts (Flair #502) so they can be
+// unit-tested directly. Importing MemoryConsolidate.ts pulls in the Harper
+// runtime (`databases` / `Resource`, storage init) and can't run outside a live
+// Harper; this module has no Harper dependency, so
+// test/unit/memory-consolidate.test.ts exercises the real shipped code.
+export function parseDuration(s) {
+    const m = s.match(/^(\d+)([dhm])$/);
+    if (!m)
+        return 30 * 86400_000;
+    const n = Number(m[1]);
+    if (m[2] === "d")
+        return n * 86400_000;
+    if (m[2] === "h")
+        return n * 3600_000;
+    if (m[2] === "m")
+        return n * 60_000;
+    return 30 * 86400_000;
+}
+/**
+ * Classify a single memory record as a promote/archive/keep candidate.
+ *
+ * Idle age is `now - (lastRetrieved ?? createdAt)`: a memory that was just
+ * written and never read has lastRetrieved=null, so without the createdAt
+ * fallback its idle age would be Infinity and a minutes-old memory would read
+ * as maximally stale and be archived (Flair #502). The createdAt fallback
+ * measures "never retrieved" from when the memory was born.
+ *
+ * A grace window (olderThanMs — the maintenance olderThan) guarantees a
+ * freshly-created memory is never an archive candidate regardless of retrieval
+ * count: archival only considers memories that have had a fair chance to be read.
+ */
+export function evaluate(record, now, olderThanMs) {
+    const ageMs = record.createdAt ? now - new Date(record.createdAt).getTime() : 0;
+    const count = record.retrievalCount ?? 0;
+    const lastUse = record.lastRetrieved ?? record.createdAt;
+    const idleMs = lastUse ? now - new Date(lastUse).getTime() : 0;
+    const daysIdle = idleMs / 86400_000;
+    const everRetrieved = record.lastRetrieved != null;
+    const { embedding, ...memory } = record;
+    // Promote: high retrieval + persistent durability
+    if (record.durability === "persistent" && count >= 5) {
+        return { memory, suggestion: "promote", reason: `Retrieved ${count} times — strong promotion candidate for permanent` };
+    }
+    // Promote: standard → persistent if retrieved frequently
+    if (record.durability === "standard" && count >= 3 && ageMs > 7 * 86400_000) {
+        return { memory, suggestion: "promote", reason: `Retrieved ${count} times over ${Math.round(ageMs / 86400_000)} days — worth persisting` };
+    }
+    // Grace window: a freshly-created memory is never an archive candidate,
+    // regardless of retrieval count (Flair #502). Archive branches below are
+    // reachable only for memories older than the maintenance window.
+    if (ageMs <= olderThanMs) {
+        return { memory, suggestion: "keep", reason: everRetrieved
+                ? `Retrieved ${count} times, ${Math.round(daysIdle)} days since last retrieval`
+                : `Created ${Math.round(ageMs / 86400_000)} days ago, not yet retrieved (within grace window)` };
+    }
+    // Archive: old + never retrieved
+    if (daysIdle > 30 && count === 0) {
+        return { memory, suggestion: "archive", reason: everRetrieved
+                ? `Not retrieved in ${Math.round(daysIdle)} days, ${Math.round(ageMs / 86400_000)} days old`
+                : `Never retrieved, ${Math.round(ageMs / 86400_000)} days old` };
+    }
+    // Archive: idle > 60 days with few retrievals
+    if (daysIdle > 60 && count < 2) {
+        return { memory, suggestion: "archive", reason: everRetrieved
+                ? `Not retrieved in ${Math.round(daysIdle)} days (only ${count} total retrievals)`
+                : `Never retrieved, ${Math.round(ageMs / 86400_000)} days old (0 total retrievals)` };
+    }
+    return { memory, suggestion: "keep", reason: everRetrieved
+            ? `Retrieved ${count} times, ${Math.round(daysIdle)} days since last retrieval`
+            : `Created ${Math.round(ageMs / 86400_000)} days ago, not yet retrieved` };
+}

package/dist/resources/scoring.js

@@ -0,0 +1,52 @@
+// ─── Temporal Decay + Relevance Scoring ─────────────────────────────────────
+// Pure scoring functions extracted from SemanticSearch.ts (OPS-AYGD) so they can
+// be unit-tested directly. Importing SemanticSearch.ts pulls in the Harper runtime
+// (storage init) and can't run outside a live Harper; this module has no Harper
+// dependency, so test/unit/temporal-scoring.test.ts exercises the real shipped code.
+export const DURABILITY_WEIGHTS = {
+    permanent: 1.0,
+    persistent: 0.9,
+    standard: 0.7,
+    ephemeral: 0.4,
+};
+// Half-life in days for exponential decay per durability level
+export const DECAY_HALF_LIFE_DAYS = {
+    permanent: Infinity, // never decays
+    persistent: 90,
+    standard: 30,
+    ephemeral: 7,
+};
+export function recencyFactor(createdAt, durability) {
+    const halfLife = DECAY_HALF_LIFE_DAYS[durability] ?? 30;
+    if (halfLife === Infinity)
+        return 1.0;
+    const ageDays = (Date.now() - Date.parse(createdAt)) / (1000 * 60 * 60 * 24);
+    const lambda = Math.LN2 / halfLife;
+    return Math.exp(-lambda * ageDays);
+}
+// OPS-AYGD: the retrieval boost was unbounded and OVERRODE semantic ranking —
+// recall-eval 2026-06-19 showed composite p@3 0.83 vs raw 1.00, with a popular doc
+// magnetised into 5/6 queries (its rBoost lifted a 0.55-0.65 semantic score above
+// the correct docs). Bounded to a gentle nudge that breaks near-ties without
+// overriding a clear semantic winner. Tuned offline against the real corpus
+// (floor 0.5 + cap 1.1 → composite p@3 recovers to 1.00, magnet eliminated).
+// A query-relative tie-breaker gate (boost only within ~0.05 of the top raw score)
+// is the principled follow-up for graduated boosting; it needs the search loop to
+// pass the candidate-set top score, so it's deferred to its own change.
+export const RBOOST_CAP = 1.1; // max +10% — a tie-breaker, not an override
+export const RBOOST_RELEVANCE_FLOOR = 0.5; // no boost at all for clearly-irrelevant docs
+export function retrievalBoost(retrievalCount) {
+    if (!retrievalCount || retrievalCount <= 0)
+        return 1.0;
+    return Math.min(1.0 + 0.1 * Math.log2(retrievalCount), RBOOST_CAP); // gentle, capped
+}
+export function compositeScore(semanticScore, record) {
+    const durability = record.durability ?? "standard";
+    const dWeight = DURABILITY_WEIGHTS[durability] ?? 0.7;
+    const rFactor = record.createdAt ? recencyFactor(record.createdAt, durability) : 1.0;
+    // OPS-AYGD: only apply the retrieval boost when the record is genuinely relevant to
+    // this query (semanticScore clears the floor). Below the floor, a popular doc gets
+    // no lift — kills the cross-query magnet while preserving boosts for relevant docs.
+    const rBoost = semanticScore >= RBOOST_RELEVANCE_FLOOR ? retrievalBoost(record.retrievalCount ?? 0) : 1.0;
+    return semanticScore * dWeight * rFactor * rBoost;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "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",