@tpsdev-ai/flair 0.2.0

package/resources/MemoryBootstrap.ts

@@ -0,0 +1,283 @@
+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 (unconditional — not subject to token budget) ---
+    // Soul is who you are. It's not optional context to be trimmed.
+    // Skill assignments (key='skill-assignment') are separated into their own section.
+    const skillAssignments: any[] = [];
+    if (includeSoul) {
+      let soulTokens = 0;
+      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}`;
+        sections.soul.push(line);
+        soulTokens += estimateTokens(line);
+      }
+      // Soul tokens are tracked but don't reduce memory budget
+      tokenBudget = maxTokens; // memory budget is separate from soul
+    }
+
+    // --- 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 (last 24-48h, standard + persistent) ---
+    const sinceDate = since
+      ? new Date(since)
+      : new Date(Date.now() - 48 * 3600_000);
+    const recent = activeMemories
+      .filter(
+        (m) =>
+          m.durability !== "permanent" &&
+          m.createdAt &&
+          new Date(m.createdAt) >= sinceDate
+      )
+      .sort((a: any, b: any) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+
+    // 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

@@ -0,0 +1,121 @@
+/**
+ * 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

@@ -0,0 +1,48 @@
+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/MemoryReflect.ts

@@ -0,0 +1,122 @@
+/**
+ * POST /MemoryReflect
+ *
+ * Gathers recent memories for an agent and returns a structured reflection
+ * prompt. The agent feeds the prompt + memories to its LLM and writes
+ * insights back as persistent memories (with derivedFrom linking).
+ *
+ * Request:
+ *   agentId      string   — which agent to reflect on
+ *   scope        string   — "recent" | "tagged" | "all" (default: "recent")
+ *   since        string?  — ISO timestamp lower bound (default: 24h ago)
+ *   maxMemories  number?  — cap (default: 50)
+ *   focus        string?  — "lessons_learned" | "patterns" | "decisions" | "errors" (default: "lessons_learned")
+ *   tag          string?  — required when scope="tagged"
+ *
+ * Response:
+ *   memories       Memory[]   — source memories included in the prompt
+ *   prompt         string     — structured LLM prompt
+ *   suggestedTags  string[]   — tags Flair detected in the source set
+ *   count          number     — number of memories included
+ */
+
+import { Resource, databases } from "@harperfast/harper";
+import { isAdmin } from "./auth-middleware.js";
+import { patchRecordSilent } from "./table-helpers.js";
+
+const FOCUS_PROMPTS: Record<string, string> = {
+  lessons_learned:
+    "Review these memories and identify concrete lessons learned. For each lesson: what happened, what you learned, and how it should change future behavior. Write atomic memories with durability=persistent.",
+  patterns:
+    "Identify recurring patterns across these memories. What themes, approaches, or outcomes appear multiple times? Extract each pattern as a persistent memory.",
+  decisions:
+    "Catalog the key decisions made and their outcomes. For each: what was decided, why, and what resulted. Promote important decisions to persistent.",
+  errors:
+    "Extract errors, bugs, and failures. For each: what failed, root cause, and fix applied. These are high-value persistent memories.",
+};
+
+export class ReflectMemories extends Resource {
+  async post(data: any) {
+    const {
+      agentId,
+      scope = "recent",
+      since,
+      maxMemories = 50,
+      focus = "lessons_learned",
+      tag,
+    } = data || {};
+
+    if (!agentId) return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
+
+    // Auth: agent can only reflect on own memories unless admin
+    const actorId = (this as any).request?.tpsAgent;
+    if (actorId && actorId !== agentId && !(await isAdmin(actorId))) {
+      return new Response(JSON.stringify({ error: "forbidden: can only reflect on own memories" }), { status: 403 });
+    }
+
+    const sinceDate = since ? new Date(since) : new Date(Date.now() - 24 * 3600_000);
+    const memories: any[] = [];
+
+    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 memories don't need reflection
+
+      if (scope === "tagged") {
+        if (!tag || !(record.tags ?? []).includes(tag)) continue;
+      } else if (scope === "recent") {
+        if (!record.createdAt || new Date(record.createdAt) < sinceDate) continue;
+      }
+      // scope="all" passes everything
+
+      const { embedding, ...rest } = record;
+      memories.push(rest);
+      if (memories.length >= maxMemories) break;
+    }
+
+    memories.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+
+    // Collect tags present in source memories
+    const tagSet = new Set<string>();
+    for (const m of memories) {
+      for (const t of m.tags ?? []) tagSet.add(t);
+    }
+
+    // Build prompt
+    const focusText = FOCUS_PROMPTS[focus] ?? FOCUS_PROMPTS.lessons_learned;
+    const memorySummary = memories
+      .map((m, i) => `[${i + 1}] (${m.id}) ${m.createdAt?.slice(0, 10) ?? "?"}: ${m.content.slice(0, 300)}`)
+      .join("\n");
+
+    const prompt = `# Memory Reflection — ${agentId}
+Focus: ${focus}
+Scope: ${scope} (since ${sinceDate.toISOString()})
+Memories: ${memories.length}
+
+## Task
+${focusText}
+
+## Source Memories
+${memorySummary || "(none)"}
+
+## Instructions
+For each insight:
+1. Write a new memory with durability=persistent
+2. Set derivedFrom=[<source memory ids>]
+3. Set tags from the source memories where relevant
+4. Keep each memory atomic — one insight per record`;
+
+    // Update lastReflected on source memories (read-modify-write to preserve embeddings)
+    const now = new Date().toISOString();
+    for (const m of memories) {
+      patchRecordSilent((databases as any).flair.Memory, m.id, { lastReflected: now });
+    }
+
+    return {
+      memories,
+      prompt,
+      suggestedTags: [...tagSet].slice(0, 20),
+      count: memories.length,
+    };
+  }
+}

package/resources/OrgEvent.ts

@@ -0,0 +1,63 @@
+/**
+ * OrgEvent.ts — Harper table resource for org-wide activity events.
+ *
+ * Auth: Ed25519 middleware sets request.tpsAgent.
+ * Write: authorId must match authenticated agent (or admin).
+ * Read: any authenticated participant can read (org-scoped).
+ */
+
+import { databases } from "@harperfast/harper";
+
+export class OrgEvent extends (databases as any).flair.OrgEvent {
+  async post(content: any, context?: any) {
+    const agentId = context?.request?.tpsAgent;
+
+    // authorId must match authenticated agent (unless admin)
+    if (agentId && !context?.request?.tpsAgentIsAdmin && content.authorId !== agentId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: authorId must match authenticated agent" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Generate composite ID if not provided
+    if (!content.id) {
+      content.id = `${content.authorId}-${Date.now()}`;
+    }
+
+    content.createdAt = new Date().toISOString();
+
+    // Harper 5: table resources use put() for create/upsert (post() removed)
+    return (databases as any).flair.OrgEvent.put(content);
+  }
+
+  async put(content: any, context?: any) {
+    const agentId = context?.request?.tpsAgent;
+
+    if (agentId && !context?.request?.tpsAgentIsAdmin && content.authorId !== agentId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: authorId must match authenticated agent" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    return (databases as any).flair.OrgEvent.put(content);
+  }
+
+  async delete(id: any, context?: any) {
+    const agentId = context?.request?.tpsAgent;
+    if (!agentId) return super.delete(id, context);
+
+    const record = await this.get(id);
+    if (!record) return super.delete(id, context);
+
+    if (!context?.request?.tpsAgentIsAdmin && record.authorId !== agentId) {
+      return new Response(
+        JSON.stringify({ error: "forbidden: cannot delete events authored by another agent" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    return super.delete(id, context);
+  }
+}