@tpsdev-ai/flair 0.3.17 → 0.3.19

package/resources/MemoryBootstrap.ts

@@ -1,323 +0,0 @@
-import { Resource, databases } from "@harperfast/harper";
-import { getEmbedding } from "./embeddings-provider.js";
-
-/**
- * POST /MemoryBootstrap
- *
- * One-call context builder for agent cold starts.
- * Returns prioritized, token-budgeted context with:
- *   1. Soul records (identity, role, preferences)
- *   2. Permanent memories (safety rules, core principles)
- *   3. Recent memories (last 24-48h standard/persistent)
- *   4. Task-relevant memories (semantic search if currentTask provided)
- *
- * Request:
- *   { agentId, currentTask?, maxTokens?, includeSoul?, since? }
- *
- * Response:
- *   { context, sections, tokenEstimate, memoriesIncluded, memoriesAvailable }
- */
-
-// Rough token estimate: ~4 chars per token for English text
-function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
-function formatMemory(m: any, supersedes?: boolean): string {
-  const tag = m.durability === "permanent" ? "🔒" : m.durability === "persistent" ? "📌" : "📝";
-  const date = m.createdAt ? ` (${m.createdAt.slice(0, 10)})` : "";
-  const chain = m.supersedes ? " [supersedes earlier decision]" : "";
-  return `${tag} ${m.content}${date}${chain}`;
-}
-
-export class BootstrapMemories extends Resource {
-  async post(data: any, _context?: any) {
-    const {
-      agentId,
-      currentTask,
-      maxTokens = 4000,
-      includeSoul = true,
-      since,
-    } = data || {};
-
-    if (!agentId) {
-      return new Response(JSON.stringify({ error: "agentId required" }), {
-        status: 400,
-        headers: { "Content-Type": "application/json" },
-      });
-    }
-
-    // Defense-in-depth: agentId must match authenticated agent
-    const authenticatedAgent: string | undefined = (this as any).request?.headers?.get?.("x-tps-agent");
-    const callerIsAdmin: boolean = (this as any).request?.tpsAgentIsAdmin === true;
-    if (authenticatedAgent && !callerIsAdmin && agentId !== authenticatedAgent) {
-      return new Response(JSON.stringify({
-        error: "forbidden: agentId must match authenticated agent",
-      }), { status: 403, headers: { "Content-Type": "application/json" } });
-    }
-
-    const sections: Record<string, string[]> = {
-      soul: [],
-      skills: [],
-      permanent: [],
-      recent: [],
-      relevant: [],
-      events: [],
-    };
-    let tokenBudget = maxTokens;
-    let memoriesIncluded = 0;
-    let memoriesAvailable = 0;
-
-    // --- 1. Soul records (budgeted — prioritized by key importance) ---
-    // Soul is who you are, but we still need to respect token budgets.
-    // Workspace files (SOUL.md, AGENTS.md) can be massive — they're already
-    // injected by the runtime via workspace context, so we prioritize
-    // concise soul entries over full file dumps.
-    const SOUL_KEY_PRIORITY: Record<string, number> = {
-      role: 0, identity: 1, thinking: 2, communication_style: 3,
-      team: 4, ownership: 5, infrastructure: 6, "user-context": 7,
-      // Full workspace files — lowest priority (runtime already injects these)
-      soul: 90, "workspace-rules": 91,
-    };
-
-    const skillAssignments: any[] = [];
-    const soulMaxTokens = Math.floor(maxTokens * 0.4); // 40% of budget for soul
-    if (includeSoul) {
-      let soulTokens = 0;
-      const soulEntries: { key: string; line: string; tokens: number; priority: number }[] = [];
-
-      for await (const record of (databases as any).flair.Soul.search()) {
-        if (record.agentId !== agentId) continue;
-        if (record.key === "skill-assignment") {
-          skillAssignments.push(record);
-          continue;
-        }
-        const line = `**${record.key}:** ${record.value}`;
-        const tokens = estimateTokens(line);
-        const priority = SOUL_KEY_PRIORITY[record.key] ?? 50;
-        soulEntries.push({ key: record.key, line, tokens, priority });
-      }
-
-      // Sort by priority (lower = more important)
-      soulEntries.sort((a, b) => a.priority - b.priority);
-
-      for (const entry of soulEntries) {
-        if (soulTokens + entry.tokens > soulMaxTokens) {
-          // Skip large entries that exceed budget — truncate or skip
-          if (entry.priority >= 90) continue; // skip full workspace files
-          // Truncate if it's important but too long
-          const maxChars = (soulMaxTokens - soulTokens) * 4;
-          if (maxChars > 100) {
-            const truncated = `**${entry.key}:** ${entry.line.slice(entry.key.length + 6, entry.key.length + 6 + maxChars)}…(truncated)`;
-            sections.soul.push(truncated);
-            soulTokens += estimateTokens(truncated);
-          }
-          continue;
-        }
-        sections.soul.push(entry.line);
-        soulTokens += entry.tokens;
-      }
-    }
-
-    // --- 1b. Skill assignments (ordered by priority, conflict detection) ---
-    if (skillAssignments.length > 0) {
-      const priorityOrder: Record<string, number> = { critical: 0, high: 1, standard: 2, low: 3 };
-      skillAssignments.sort((a, b) => {
-        const pa = priorityOrder[a.priority ?? "standard"] ?? 2;
-        const pb = priorityOrder[b.priority ?? "standard"] ?? 2;
-        return pa - pb;
-      });
-
-      // Detect conflicts at same priority level
-      const byPriority = new Map<string, any[]>();
-      for (const skill of skillAssignments) {
-        const p = skill.priority ?? "standard";
-        if (!byPriority.has(p)) byPriority.set(p, []);
-        byPriority.get(p)!.push(skill);
-      }
-
-      for (const skill of skillAssignments) {
-        const p = skill.priority ?? "standard";
-        let meta: any = {};
-        try { meta = typeof skill.metadata === "string" ? JSON.parse(skill.metadata) : (skill.metadata ?? {}); } catch {}
-        const source = meta.source ? `, source: ${meta.source}` : "";
-        let line = `- ${skill.value} (${p} priority${source})`;
-        // Flag conflicts at same priority level
-        const peers = byPriority.get(p) ?? [];
-        if (peers.length > 1) {
-          line += " [SKILL_CONFLICT]";
-        }
-        sections.skills.push(line);
-      }
-    }
-
-    // --- 2. Permanent memories (always included, highest priority) ---
-    const allMemories: any[] = [];
-    for await (const record of (databases as any).flair.Memory.search()) {
-      if (record.agentId !== agentId) continue;
-      if (record.expiresAt && Date.parse(record.expiresAt) < Date.now()) continue;
-      allMemories.push(record);
-    }
-    memoriesAvailable = allMemories.length;
-
-    // Build superseded set: exclude memories that have been replaced by newer ones
-    const supersededIds = new Set<string>();
-    for (const m of allMemories) {
-      if (m.supersedes) supersededIds.add(m.supersedes);
-    }
-    const activeMemories = allMemories.filter((m) => !supersededIds.has(m.id));
-
-    const permanent = activeMemories.filter((m) => m.durability === "permanent");
-    for (const m of permanent) {
-      const line = formatMemory(m);
-      const cost = estimateTokens(line);
-      if (cost <= tokenBudget) {
-        sections.permanent.push(line);
-        tokenBudget -= cost;
-        memoriesIncluded++;
-      }
-    }
-
-    // --- 3. Recent memories (adaptive window) ---
-    // Start with 48h. If nothing found, widen to 7d, then 30d.
-    // This prevents empty recent sections for agents that were idle.
-    const nonPermanent = activeMemories
-      .filter((m) => m.durability !== "permanent" && m.createdAt)
-      .sort((a: any, b: any) => (b.createdAt || "").localeCompare(a.createdAt || ""));
-
-    let effectiveSince: Date;
-    if (since) {
-      effectiveSince = new Date(since);
-    } else {
-      const windows = [48 * 3600_000, 7 * 24 * 3600_000, 30 * 24 * 3600_000];
-      effectiveSince = new Date(Date.now() - windows[0]);
-      for (const w of windows) {
-        effectiveSince = new Date(Date.now() - w);
-        const count = nonPermanent.filter((m) => new Date(m.createdAt!) >= effectiveSince).length;
-        if (count >= 3) break; // found enough recent memories
-      }
-    }
-
-    const recent = nonPermanent.filter((m) => new Date(m.createdAt!) >= effectiveSince);
-
-    // Budget: up to 40% of remaining for recent
-    const recentBudget = Math.floor(tokenBudget * 0.4);
-    let recentSpent = 0;
-    for (const m of recent) {
-      const line = formatMemory(m);
-      const cost = estimateTokens(line);
-      if (recentSpent + cost > recentBudget) continue;
-      sections.recent.push(line);
-      recentSpent += cost;
-      tokenBudget -= cost;
-      memoriesIncluded++;
-    }
-
-    // --- 4. Task-relevant memories (semantic search) ---
-    if (currentTask && tokenBudget > 200) {
-      let queryEmbedding: number[] | null = null;
-      try {
-        queryEmbedding = await getEmbedding(currentTask);
-      } catch {}
-
-      if (queryEmbedding) {
-        // Score all non-included memories by relevance
-        const includedIds = new Set([
-          ...permanent.map((m) => m.id),
-          ...recent.filter((_, i) => i < sections.recent.length).map((m) => m.id),
-        ]);
-
-        const scored = allMemories
-          .filter((m) => !includedIds.has(m.id) && !supersededIds.has(m.id) && m.embedding?.length > 100)
-          .map((m) => {
-            let dot = 0;
-            const len = Math.min(queryEmbedding!.length, m.embedding.length);
-            for (let i = 0; i < len; i++) dot += queryEmbedding![i] * m.embedding[i];
-            return { memory: m, score: dot };
-          })
-          .filter((s) => s.score > 0.3)
-          .sort((a, b) => b.score - a.score);
-
-        for (const { memory: m } of scored) {
-          const line = formatMemory(m);
-          const cost = estimateTokens(line);
-          if (cost > tokenBudget) continue;
-          sections.relevant.push(line);
-          tokenBudget -= cost;
-          memoriesIncluded++;
-        }
-      }
-    }
-
-    // --- 5. Recent OrgEvents for this agent ---
-    try {
-      const eventSince = data?.lastBootAt
-        ? new Date(data.lastBootAt)
-        : new Date(Date.now() - 24 * 3600_000);
-      const eventSinceStr = eventSince.toISOString();
-      const eventResults: any[] = [];
-
-      for await (const event of (databases as any).flair.OrgEvent.search()) {
-        if (!event.createdAt || event.createdAt < eventSinceStr) continue;
-        if (event.expiresAt && new Date(event.expiresAt) < new Date()) continue;
-        const targets = event.targetIds;
-        const isRelevant = !targets || targets.length === 0 || targets.includes(agentId);
-        if (!isRelevant) continue;
-        eventResults.push(event);
-      }
-
-      eventResults.sort((a: any, b: any) => (a.createdAt || "").localeCompare(b.createdAt || ""));
-      for (const evt of eventResults.slice(0, 10)) {
-        const elapsed = Date.now() - new Date(evt.createdAt).getTime();
-        const mins = Math.floor(elapsed / 60_000);
-        const relTime = mins < 60 ? `${mins}min ago` : `${Math.floor(mins / 60)}h ago`;
-        sections.events.push(`- ${evt.kind}: ${evt.summary} (${relTime})`);
-      }
-    } catch {
-      // non-fatal: OrgEvent table may not exist yet
-    }
-
-    // --- Build context string ---
-    const parts: string[] = [];
-
-    if (sections.soul.length > 0) {
-      parts.push("## Identity\n" + sections.soul.join("\n"));
-    }
-    if (sections.skills.length > 0) {
-      parts.push("## Active Skills\n" + sections.skills.join("\n"));
-    }
-    if (sections.permanent.length > 0) {
-      parts.push("## Core Principles\n" + sections.permanent.join("\n"));
-    }
-    if (sections.recent.length > 0) {
-      parts.push("## Recent Context\n" + sections.recent.join("\n"));
-    }
-    if (sections.relevant.length > 0) {
-      parts.push("## Relevant Knowledge\n" + sections.relevant.join("\n"));
-    }
-    if (sections.events.length > 0) {
-      parts.push("## Recent Org Events\n" + sections.events.join("\n"));
-    }
-
-    const context = parts.join("\n\n");
-    const soulTokens = sections.soul.reduce((sum, line) => sum + estimateTokens(line), 0);
-    const memoryTokens = maxTokens - tokenBudget;
-
-    return {
-      context,
-      sections: {
-        soul: sections.soul.length,
-        skills: sections.skills.length,
-        permanent: sections.permanent.length,
-        recent: sections.recent.length,
-        relevant: sections.relevant.length,
-        events: sections.events.length,
-      },
-      tokenEstimate: soulTokens + memoryTokens,
-      soulTokens,
-      memoryTokens,
-      memoriesIncluded,
-      memoriesAvailable,
-    };
-  }
-}

package/resources/MemoryConsolidate.ts

@@ -1,121 +0,0 @@
-/**
- * POST /MemoryConsolidate
- *
- * Reviews an agent's persistent memories and returns candidates for
- * promotion (standard→persistent or persistent→permanent proposal) or
- * archival, based on retrieval count and age.
- *
- * Request:
- *   agentId   string   — which agent
- *   scope     string   — "persistent" | "standard" | "all" (default: "persistent")
- *   olderThan string?  — duration like "30d", "7d" (default: "30d")
- *   limit     number?  — max candidates (default: 20)
- *
- * Response:
- *   candidates  Array<{ memory, suggestion, reason }>
- *   prompt      string
- */
-
-import { Resource, databases } from "@harperfast/harper";
-import { isAdmin } from "./auth-middleware.js";
-
-function parseDuration(s: string): number {
-  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;
-}
-
-type Suggestion = "promote" | "archive" | "keep";
-
-interface Candidate {
-  memory: Record<string, unknown>;
-  suggestion: Suggestion;
-  reason: string;
-}
-
-function evaluate(record: any, now: number, olderThanMs: number): Candidate {
-  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` };
-}
-
-export class ConsolidateMemories extends Resource {
-  async post(data: any) {
-    const { agentId, scope = "persistent", olderThan = "30d", limit = 20 } = data || {};
-
-    if (!agentId) return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
-
-    const actorId = (this as any).request?.tpsAgent;
-    if (actorId && actorId !== agentId && !(await isAdmin(actorId))) {
-      return new Response(JSON.stringify({ error: "forbidden: can only consolidate own memories" }), { status: 403 });
-    }
-
-    const olderThanMs = parseDuration(olderThan);
-    const now = Date.now();
-    const candidates: Candidate[] = [];
-
-    for await (const record of (databases as any).flair.Memory.search()) {
-      if (record.agentId !== agentId) continue;
-      if (record.archived) continue;
-      if (record.durability === "permanent") continue; // permanent can't be demoted
-
-      if (scope === "persistent" && record.durability !== "persistent") continue;
-      if (scope === "standard" && record.durability !== "standard") continue;
-
-      const candidate = evaluate(record, now, olderThanMs);
-      candidates.push(candidate);
-      if (candidates.length >= limit * 3) break; // over-fetch to sort
-    }
-
-    // Sort: promote first, then archive, then keep
-    const order: Record<Suggestion, number> = { promote: 0, archive: 1, keep: 2 };
-    candidates.sort((a, b) => order[a.suggestion] - order[b.suggestion]);
-    const top = candidates.slice(0, limit);
-
-    const promoteCount = top.filter(c => c.suggestion === "promote").length;
-    const archiveCount = top.filter(c => c.suggestion === "archive").length;
-
-    const prompt = `# Memory Consolidation Review — ${agentId}
-Scope: ${scope} | OlderThan: ${olderThan} | Candidates: ${top.length}
-
-Summary: ${promoteCount} promote candidates, ${archiveCount} archive candidates.
-
-For each candidate below:
-- PROMOTE: Upgrade standard→persistent (self-approve) or propose persistent→permanent (needs human)
-- ARCHIVE: Soft-delete (hidden from search, recoverable)
-- KEEP: No action
-
-Use: tps memory approve <id> | tps memory archive <id> | skip`;
-
-    return { candidates: top, prompt };
-  }
-}

package/resources/MemoryFeed.ts

@@ -1,48 +0,0 @@
-import { Resource, databases } from "@harperfast/harper";
-import { computeContentHash, findExistingMemoryByContentHash } from "./memory-feed-lib.js";
-
-export class FeedMemories extends Resource {
-  async post(content: any) {
-    const agentId = String(content?.agentId ?? "");
-    const body = String(content?.content ?? "");
-    if (!agentId || !body) {
-      return new Response(JSON.stringify({ error: "agentId and content are required" }), {
-        status: 400,
-        headers: { "Content-Type": "application/json" },
-      });
-    }
-
-    const now = new Date().toISOString();
-    const contentHash = computeContentHash(agentId, body);
-
-    const existing = await findExistingMemoryByContentHash((databases as any).flair.Memory.search(), agentId, contentHash);
-    if (existing) return existing;
-
-    const record = {
-      ...content,
-      id: content.id ?? `${agentId}-${Date.now()}`,
-      agentId,
-      content: body,
-      contentHash,
-      durability: content.durability ?? "standard",
-      createdAt: content.createdAt ?? now,
-      updatedAt: content.updatedAt ?? now,
-      archived: content.archived ?? false,
-    };
-
-    await (databases as any).flair.Memory.put(record);
-    return record;
-  }
-
-  async *connect(target: any, incomingMessages: any) {
-    const subscription = await (databases as any).flair.Memory.subscribe(target);
-
-    if (!incomingMessages) {
-      return subscription;
-    }
-
-    for await (const event of subscription) {
-      yield event;
-    }
-  }
-}

package/resources/MemoryMaintenance.ts

@@ -1,95 +0,0 @@
-/**
- * MemoryMaintenance.ts — Maintenance worker for memory hygiene.
- *
- * POST /MemoryMaintenance/ — runs cleanup tasks:
- *   1. Delete expired ephemeral memories (expiresAt < now)
- *   2. Archive old session memories (> 30 days, standard durability)
- *   3. Report stats
- *
- * Designed to run periodically (daily cron or heartbeat).
- * Requires admin auth.
- */
-
-export default class MemoryMaintenance {
-  static ROUTE = "MemoryMaintenance";
-  static METHOD = "POST";
-
-  async post(data: any) {
-    const { databases }: any = this;
-    const request = (this as any).request;
-    const { dryRun = false, agentId } = data || {};
-
-    // Scope to authenticated agent. Admin can pass agentId for system-wide
-    // maintenance; non-admin always scoped to their own agent.
-    const authAgent = request?.headers?.get?.("x-tps-agent");
-    const isAdmin = (request as any)?.tpsAgentIsAdmin === true;
-    const targetAgent = isAdmin && agentId ? agentId : authAgent;
-
-    if (!targetAgent && !isAdmin) {
-      return { error: "agentId required" };
-    }
-
-    const now = new Date();
-    const stats = { expired: 0, archived: 0, total: 0, errors: 0, agent: targetAgent || "all" };
-
-    try {
-      for await (const record of (databases as any).flair.Memory.search()) {
-        // Skip records not belonging to target agent (unless admin running system-wide)
-        if (targetAgent && record.agentId !== targetAgent) continue;
-        stats.total++;
-
-        // 1. Delete expired memories
-        if (record.expiresAt && new Date(record.expiresAt) < now) {
-          if (!dryRun) {
-            try {
-              await (databases as any).flair.Memory.delete(record.id);
-              stats.expired++;
-            } catch {
-              stats.errors++;
-            }
-          } else {
-            stats.expired++;
-          }
-          continue;
-        }
-
-        // 2. Archive old standard session memories (> 30 days)
-        // These are low-value session notes that weren't promoted to persistent.
-        // Archiving removes them from search results but keeps the data.
-        if (
-          record.durability === "standard" &&
-          record.type === "session" &&
-          !record.archived &&
-          record.createdAt
-        ) {
-          const ageMs = now.getTime() - new Date(record.createdAt).getTime();
-          const ageDays = ageMs / (24 * 3600_000);
-          if (ageDays > 30) {
-            if (!dryRun) {
-              try {
-                // Soft archive — set archived flag, keep data
-                await (databases as any).flair.Memory.update(record.id, {
-                  ...record,
-                  archived: true,
-                  archivedAt: now.toISOString(),
-                });
-                stats.archived++;
-              } catch {
-                stats.errors++;
-              }
-            } else {
-              stats.archived++;
-            }
-          }
-        }
-      }
-    } catch (err: any) {
-      return { error: err.message, stats };
-    }
-
-    return {
-      message: dryRun ? "Dry run complete" : "Maintenance complete",
-      stats,
-    };
-  }
-}