@tpsdev-ai/flair 0.2.0

package/dist/resources/IngestEvents.js

@@ -0,0 +1,149 @@
+/**
+ * IngestEvents.ts — Observatory ingestion endpoint.
+ *
+ * POST /IngestEvents
+ * Auth: TPS-Ed25519 signed by the office's private key (verified against
+ *       ObsOffice.publicKey stored at registration time).
+ *
+ * Body: {
+ *   officeId: string;
+ *   events:   OrgEventRecord[];
+ *   agents:   AgentStatus[];
+ *   syncedAt: string;
+ * }
+ *
+ * Actions:
+ *   1. Verify Ed25519 signature against stored office public key
+ *   2. Upsert ObsAgentSnapshot for each agent
+ *   3. Insert ObsEventFeed for each new event (30-day TTL)
+ *   4. Update ObsOffice.lastSeen + agentCount
+ *
+ * Rate limit: 1 call / 10s per office (enforced by createdAt delta check)
+ * Batch limit: 100 events per call
+ */
+import { Resource, databases } from "@harperfast/harper";
+import { createPublicKey, verify } from "node:crypto";
+const BATCH_LIMIT = 100;
+const RATE_LIMIT_MS = 10_000;
+const EVENT_TTL_DAYS = 30;
+function verifyEd25519Signature(publicKeyHex, authHeader, officeId) {
+    try {
+        // Header format: TPS-Ed25519 officeId:ts:nonce:sig
+        const prefix = "TPS-Ed25519 ";
+        if (!authHeader.startsWith(prefix))
+            return false;
+        const parts = authHeader.slice(prefix.length).split(":");
+        if (parts.length < 4)
+            return false;
+        const [id, ts, nonce, ...sigParts] = parts;
+        const sig = sigParts.join(":");
+        if (id !== officeId)
+            return false;
+        // Replay protection: reject signatures older than 5 minutes
+        const age = Date.now() - Number(ts);
+        if (age > 5 * 60 * 1000 || age < -30_000)
+            return false;
+        const pubKeyBytes = Buffer.from(publicKeyHex.replace(/=\s*/g, ""), "hex");
+        const spkiHeader = Buffer.from("302a300506032b6570032100", "hex");
+        const pubKey = createPublicKey({ key: Buffer.concat([spkiHeader, pubKeyBytes]), format: "der", type: "spki" });
+        const payload = Buffer.from(`${id}:${ts}:${nonce}:POST:/IngestEvents`);
+        const sigBuf = Buffer.from(sig, "base64");
+        return verify(null, payload, pubKey, sigBuf);
+    }
+    catch {
+        return false;
+    }
+}
+export class IngestEvents extends Resource {
+    async post(body, context) {
+        const request = this.request;
+        const authHeader = request?.headers?.get?.("authorization") ?? request?.headers?.authorization;
+        // Parse and validate body
+        let payload;
+        try {
+            payload = (typeof body === "string" ? JSON.parse(body) : body);
+        }
+        catch {
+            return new Response(JSON.stringify({ error: "invalid JSON" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const { officeId, events = [], agents = [], syncedAt } = payload;
+        if (!officeId) {
+            return new Response(JSON.stringify({ error: "officeId required" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        // Look up the office
+        const office = await databases.flair.ObsOffice.get(officeId).catch(() => null);
+        if (!office) {
+            return new Response(JSON.stringify({ error: "office not registered — POST /ObsOffice first" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        // Verify Ed25519 signature
+        if (!authHeader || !verifyEd25519Signature(String(office.publicKey), authHeader, officeId)) {
+            return new Response(JSON.stringify({ error: "invalid signature" }), { status: 401, headers: { "Content-Type": "application/json" } });
+        }
+        // Rate limit check
+        if (office.lastSeen) {
+            const msSinceLastSync = Date.now() - new Date(office.lastSeen).getTime();
+            if (msSinceLastSync < RATE_LIMIT_MS) {
+                return new Response(JSON.stringify({ error: "rate limit: 1 call per 10s" }), { status: 429, headers: { "Content-Type": "application/json" } });
+            }
+        }
+        // Batch limit
+        if (events.length > BATCH_LIMIT) {
+            return new Response(JSON.stringify({ error: `batch limit: max ${BATCH_LIMIT} events` }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const now = new Date().toISOString();
+        const expiresAt = new Date(Date.now() + EVENT_TTL_DAYS * 24 * 60 * 60 * 1000).toISOString();
+        // Upsert agent snapshots
+        for (const agent of agents) {
+            if (!agent.agentId)
+                continue;
+            const snapshotId = `${officeId}:${agent.agentId}`;
+            await databases.flair.ObsAgentSnapshot.put({
+                id: snapshotId,
+                officeId,
+                agentId: agent.agentId,
+                name: agent.name ?? agent.agentId,
+                role: agent.role,
+                status: agent.status ?? "unknown",
+                model: agent.model,
+                lastActivity: agent.lastSeen ?? now,
+                lastHeartbeat: now,
+                updatedAt: now,
+            }).catch((e) => console.warn(`[IngestEvents] snapshot upsert failed for ${snapshotId}: ${e.message}`));
+        }
+        // Insert event feed entries (skip duplicates)
+        let inserted = 0;
+        for (const ev of events) {
+            if (!ev.id || !ev.kind)
+                continue;
+            const feedId = `${officeId}:${ev.id}`;
+            const existing = await databases.flair.ObsEventFeed.get(feedId).catch(() => null);
+            if (existing)
+                continue;
+            await databases.flair.ObsEventFeed.put({
+                id: feedId,
+                officeId,
+                kind: ev.kind,
+                authorId: ev.authorId,
+                summary: ev.summary,
+                refId: ev.refId,
+                scope: ev.scope,
+                createdAt: ev.createdAt,
+                receivedAt: now,
+                expiresAt,
+            }).catch((e) => console.warn(`[IngestEvents] event insert failed for ${feedId}: ${e.message}`));
+            inserted++;
+        }
+        // Update office lastSeen + agentCount
+        await databases.flair.ObsOffice.put({
+            ...office,
+            status: "online",
+            lastSeen: now,
+            agentCount: agents.length,
+            updatedAt: now,
+        }).catch(() => { });
+        return new Response(JSON.stringify({ ok: true, events: inserted, agents: agents.length }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+}

package/dist/resources/Integration.js

@@ -0,0 +1,13 @@
+import { databases } from "@harperfast/harper";
+export class Integration extends databases.flair.Integration {
+    async post(content, context) {
+        // S31-A: API never accepts plaintext credentials.
+        if (typeof content?.credential === "string" || typeof content?.token === "string") {
+            return new Response(JSON.stringify({ error: "plaintext_credentials_forbidden" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        return super.post(content, context);
+    }
+}

package/dist/resources/IssueTokens.js

@@ -0,0 +1,19 @@
+import { Resource, databases } from "@harperfast/harper";
+export class IssueTokens extends Resource {
+    static loadAsInstance = false;
+    async get(_target) {
+        const { refresh_token: refreshToken, operation_token: jwt } = await databases.system.hdb_user.operation({ operation: "create_authentication_tokens" }, this.getContext());
+        return { refreshToken, jwt };
+    }
+    async post(_target, data) {
+        if (!data?.username || !data?.password) {
+            throw new Error("username and password are required");
+        }
+        const { refresh_token: refreshToken, operation_token: jwt } = await databases.system.hdb_user.operation({
+            operation: "create_authentication_tokens",
+            username: data.username,
+            password: data.password,
+        });
+        return { refreshToken, jwt };
+    }
+}

package/dist/resources/Memory.js

@@ -0,0 +1,122 @@
+import { databases } from "@harperfast/harper";
+import { patchRecord } from "./table-helpers.js";
+import { isAdmin } from "./auth-middleware.js";
+export class Memory extends databases.flair.Memory {
+    /**
+     * Override search() to scope collection GETs by authenticated agent.
+     *
+     * Security Critical: the agentId condition is wrapped as the outermost
+     * `and` block so user-supplied query operators cannot bypass it via
+     * boolean injection (e.g. [..., "or", { wildcard }]).
+     *
+     * Admin agents and unauthenticated internal calls pass through unfiltered.
+     * Non-admin calls also check MemoryGrant to include granted memories.
+     */
+    async search(query) {
+        // Access request context via Harper's Resource instance context
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const authAgent = request?.tpsAgent;
+        const isAdminAgent = request?.tpsAgentIsAdmin ?? false;
+        // No auth context (internal admin call) or admin agent — unfiltered
+        if (!authAgent || isAdminAgent) {
+            return super.search(query);
+        }
+        // Collect agentIds this agent may read: own + any granted owners
+        const allowedOwners = [authAgent];
+        try {
+            for await (const grant of databases.flair.MemoryGrant.search({
+                conditions: [{ attribute: "granteeId", comparator: "equals", value: authAgent }],
+            })) {
+                if (grant.ownerId && (grant.scope === "read" || grant.scope === "search")) {
+                    allowedOwners.push(grant.ownerId);
+                }
+            }
+        }
+        catch { /* MemoryGrant table not yet populated — ignore */ }
+        // Build the agentId scope condition
+        const agentIdCondition = allowedOwners.length === 1
+            ? { attribute: "agentId", comparator: "equals", value: allowedOwners[0] }
+            : { conditions: allowedOwners.map(id => ({ attribute: "agentId", comparator: "equals", value: id })), operator: "or" };
+        // Harper passes `query` as a RequestTarget (extends URLSearchParams) with pathname, id, etc.
+        // Table.search() reads `target.conditions` from it. We inject our scope condition there.
+        if (query && typeof query === "object" && !Array.isArray(query)) {
+            const existing = query.conditions ?? [];
+            query.conditions = Array.isArray(existing)
+                ? [agentIdCondition, ...existing]
+                : [agentIdCondition, existing];
+            return super.search(query);
+        }
+        // Fallback: plain array or no query (internal calls)
+        const conditions = Array.isArray(query) && query.length > 0
+            ? [agentIdCondition, ...query]
+            : [agentIdCondition];
+        return super.search(conditions);
+    }
+    async post(content, context) {
+        content.durability ||= "standard";
+        content.createdAt = new Date().toISOString();
+        content.updatedAt = content.createdAt;
+        content.archived = content.archived ?? false;
+        // Validate derivedFrom source IDs exist (best-effort, non-blocking)
+        if (Array.isArray(content.derivedFrom) && content.derivedFrom.length > 0) {
+            const now = content.createdAt;
+            for (const sourceId of content.derivedFrom) {
+                try {
+                    const src = await databases.flair.Memory.get(sourceId);
+                    if (src) {
+                        patchRecord(databases.flair.Memory, sourceId, { lastReflected: now }).catch(() => { });
+                    }
+                }
+                catch { }
+            }
+        }
+        // supersedes: optional reference to the ID of the memory this one replaces
+        if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
+            return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
+                status: 400, headers: { "Content-Type": "application/json" },
+            });
+        }
+        if (content.durability === "ephemeral" && !content.expiresAt) {
+            const ttlHours = Number(process.env.FLAIR_EPHEMERAL_TTL_HOURS || 24);
+            content.expiresAt = new Date(Date.now() + ttlHours * 3600_000).toISOString();
+        }
+        return super.post(content);
+    }
+    async put(content) {
+        const now = new Date().toISOString();
+        content.updatedAt = now;
+        // If archiving, record who + when
+        if (content.archived === true && !content.archivedAt) {
+            content.archivedAt = now;
+            // archivedBy should be set by the caller (CLI stamps req.tpsAgent via query param)
+        }
+        // If approving promotion, record timestamp
+        if (content.promotionStatus === "approved" && !content.promotedAt) {
+            content.promotedAt = now;
+        }
+        // Upgrade to permanent when approved
+        if (content.promotionStatus === "approved") {
+            content.durability = "permanent";
+        }
+        return super.put(content);
+    }
+    async delete(id) {
+        const record = await this.get(id);
+        if (!record)
+            return super.delete(id);
+        if (record.durability === "permanent") {
+            // Middleware already guards this for non-admins, but belt-and-suspenders
+            const ctx = this.getContext?.();
+            const request = ctx?.request ?? ctx;
+            const actorId = request?.tpsAgent;
+            if (actorId && !(await isAdmin(actorId))) {
+                return new Response(JSON.stringify({ error: "permanent_memory_cannot_be_deleted_by_non_admin" }), {
+                    status: 403,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+        }
+        return super.delete(id);
+    }
+}

package/dist/resources/MemoryBootstrap.js

@@ -0,0 +1,263 @@
+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) {
+    return Math.ceil(text.length / 4);
+}
+function formatMemory(m, supersedes) {
+    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, _context) {
+        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 = this.request?.headers?.get?.("x-tps-agent");
+        const callerIsAdmin = this.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 = {
+            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 = [];
+        if (includeSoul) {
+            let soulTokens = 0;
+            for await (const record of databases.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 = { 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();
+            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 = {};
+                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 = [];
+        for await (const record of databases.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();
+        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, b) => (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 = 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 = [];
+            for await (const event of databases.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, b) => (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 = [];
+        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/dist/resources/MemoryConsolidate.js

@@ -0,0 +1,105 @@
+/**
+ * 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) {
+    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` };
+}
+export class ConsolidateMemories extends Resource {
+    async post(data) {
+        const { agentId, scope = "persistent", olderThan = "30d", limit = 20 } = data || {};
+        if (!agentId)
+            return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
+        const actorId = this.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 = [];
+        for await (const record of databases.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 = { 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 };
+    }
+}