@muxoai/sdk 1.2.3 → 1.4.2

package/dist/providers/supermemory.js

@@ -0,0 +1,778 @@
+import crypto from "node:crypto";
+import Supermemory from "supermemory";
+import { formatHumanFriendlyExplanation } from "../policy.js";
+// Profile buckets can hold plain strings or memory objects depending on API version.
+function toFactTexts(items) {
+    if (!Array.isArray(items))
+        return [];
+    return items
+        .map((item) => {
+        if (item == null)
+            return "";
+        if (typeof item !== "object")
+            return String(item);
+        const o = item;
+        const text = o.memory ?? o.content ?? o.text ?? o.fact ?? o.value ?? o.summary ?? o.title;
+        return typeof text === "string" ? text : JSON.stringify(item);
+    })
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Supermemory v5 Contextual Brain & Context-Aware Tool Call Adapter.
+ * Uses deterministic per-workspace namespaces (`/ns/muxo-v5-<hash>/...`)
+ * and strict secret redaction so credentials never enter external memory.
+ */
+export class SupermemoryAdapter {
+    config;
+    client;
+    byokClients = new Map();
+    unavailableUntil = 0;
+    constructor(config) {
+        this.config = config;
+        if (config.supermemoryApiKey) {
+            this.client = new Supermemory({
+                apiKey: config.supermemoryApiKey,
+                baseUrl: config.supermemoryBaseUrl,
+                maxRetries: 0,
+                timeoutInSeconds: 2,
+            });
+        }
+        else {
+            this.client = null;
+        }
+    }
+    resolveClient(apiKeyOverride) {
+        const trimmedByok = String(apiKeyOverride || "").trim();
+        if (trimmedByok) {
+            let byokClient = this.byokClients.get(trimmedByok);
+            if (!byokClient) {
+                byokClient = new Supermemory({
+                    apiKey: trimmedByok,
+                    baseUrl: this.config.supermemoryBaseUrl,
+                    maxRetries: 0,
+                    timeoutInSeconds: 2,
+                });
+                this.byokClients.set(trimmedByok, byokClient);
+            }
+            return {
+                client: byokClient,
+                fundingSource: "customer_byok_supermemory",
+            };
+        }
+        if (this.client) {
+            return {
+                client: this.client,
+                fundingSource: "muxo_funded",
+            };
+        }
+        return {
+            client: null,
+            fundingSource: "local_fallback",
+        };
+    }
+    withTimeout(fn, ms = 1000) {
+        if (Date.now() < this.unavailableUntil) {
+            return Promise.resolve(null);
+        }
+        return Promise.race([
+            fn(),
+            new Promise((resolve) => {
+                const t = setTimeout(() => {
+                    this.unavailableUntil = Date.now() + 30_000;
+                    resolve(null);
+                }, ms);
+                t.unref?.();
+            }),
+        ]).catch(() => {
+            this.unavailableUntil = Date.now() + 30_000;
+            return null;
+        });
+    }
+    isEnabled(apiKeyOverride) {
+        return Boolean(this.resolveClient(apiKeyOverride).client);
+    }
+    /**
+     * Derives a strict Supermemory v5 namespace (`^[a-zA-Z0-9_:-]+$`) scoped to a workspace.
+     */
+    namespaceForWorkspace(workspaceId) {
+        const hash = crypto
+            .createHash("sha256")
+            .update(`muxo-v5-ns:${workspaceId}`)
+            .digest("hex")
+            .slice(0, 24);
+        return `muxo-v5-${hash}`;
+    }
+    getWorkspaceNamespace(workspaceId) {
+        return this.namespaceForWorkspace(workspaceId);
+    }
+    /**
+     * Strips any API keys, bearer tokens, connection strings, or .env secret assignments
+     * before content is stored in Supermemory (AGENTS.md Invariant #11 & #12).
+     */
+    sanitizeContent(raw) {
+        return raw
+            .replace(/\b(sk_live_|sk_test_|mk_live_|mk_test_|sm_|ak_|uak_|rk_live_|rk_test_|whsec_|ghp_|xoxb-|xoxp-)[A-Za-z0-9_\-]{6,}/g, "[REDACTED_KEY]")
+            .replace(/\b(postgres(?:ql)?|mysql|redis|rediss|mongodb(?:\+srv)?):\/\/[^\s"'`]+/gi, "$1://[REDACTED_CONNECTION_URI]")
+            .replace(/\b([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY|CONNECTION_STRING)[A-Z0-9_]*)\s*=\s*[^\s\n]+/g, "$1=[REDACTED]");
+    }
+    /**
+     * Fetches the workspace's static + dynamic profile and optionally semantic search results
+     * in a single fail-open call. Supports customer BYOK `supermemory` keys via `apiKeyOverride`.
+     */
+    async getContextForWorkspace(workspaceIdOrParams, optionalQuery, optionalApiKeyOverride) {
+        const params = typeof workspaceIdOrParams === "string"
+            ? {
+                workspaceId: workspaceIdOrParams,
+                query: optionalQuery,
+                limit: 5,
+                apiKeyOverride: optionalApiKeyOverride,
+            }
+            : workspaceIdOrParams;
+        const namespace = this.namespaceForWorkspace(params.workspaceId);
+        const { client, fundingSource } = this.resolveClient(params.apiKeyOverride);
+        if (!client) {
+            return {
+                enabled: false,
+                namespace,
+                fundingSource,
+                staticFacts: [],
+                dynamicContext: [],
+                recalledMemories: [],
+                formattedPromptContext: "Supermemory v5 disabled (no API key configured).",
+                profileMarkdown: "",
+                profile: { static: [], dynamic: [], preferences: [] },
+                relevantMemories: [],
+            };
+        }
+        const limit = Math.min(10, Math.max(1, Number(params.limit || 5)));
+        let staticFacts = [];
+        let dynamicFacts = [];
+        let preferences = [];
+        const relevantMemories = [];
+        const [profileOutcome, searchOutcome] = await Promise.allSettled([
+            this.withTimeout(() => client.profile(namespace, {
+                ...(params.query ? { q: params.query } : {}),
+            }), 1000),
+            params.query && params.query.trim().length > 0
+                ? this.withTimeout(() => client.search(namespace, {
+                    query: params.query.trim(),
+                    limit,
+                    searchMode: "hybrid",
+                    include: { documents: true, forgotten: false, related: false },
+                    rewriteQuery: false,
+                }), 1000)
+                : Promise.resolve(null),
+        ]);
+        if (profileOutcome.status === "fulfilled" && profileOutcome.value) {
+            const profileRes = profileOutcome.value;
+            staticFacts = toFactTexts(profileRes?.profile?.static);
+            dynamicFacts = toFactTexts(profileRes?.profile?.dynamic);
+            preferences = toFactTexts(profileRes?.profile?.buckets?.preferences);
+        }
+        if (searchOutcome.status === "fulfilled" && searchOutcome.value) {
+            const searchRes = searchOutcome.value;
+            for (const item of (searchRes?.results || []).slice(0, limit)) {
+                const doc = item.included?.document;
+                const title = String(doc?.metadata?.title ||
+                    doc?.title ||
+                    item.memory ||
+                    item.chunk ||
+                    "Workspace Memory").slice(0, 120);
+                const snippet = String(item.memory || item.chunk || doc?.metadata?.summary || "").slice(0, 300);
+                relevantMemories.push({
+                    documentId: String(doc?.id || item.id || ""),
+                    title,
+                    snippet,
+                    similarity: Number(item.similarity || 0),
+                });
+            }
+        }
+        const promptLines = [
+            `[Supermemory Brain — Namespace: ${namespace}]`,
+        ];
+        if (staticFacts.length > 0) {
+            promptLines.push(`Static Facts: ${staticFacts.join(" | ")}`);
+        }
+        if (dynamicFacts.length > 0) {
+            promptLines.push(`Dynamic Context: ${dynamicFacts.join(" | ")}`);
+        }
+        if (relevantMemories.length > 0) {
+            promptLines.push(`Recalled Memories: ${relevantMemories.map((m) => `${m.title}: ${m.snippet}`).join(" | ")}`);
+        }
+        const mdLines = [`## Workspace Profile (${namespace})`];
+        if (staticFacts.length > 0) {
+            mdLines.push("### Static Facts", ...staticFacts.map((f) => `- ${f}`));
+        }
+        if (dynamicFacts.length > 0) {
+            mdLines.push("### Dynamic Context", ...dynamicFacts.map((f) => `- ${f}`));
+        }
+        if (preferences.length > 0) {
+            mdLines.push("### Preferences", ...preferences.map((f) => `- ${f}`));
+        }
+        const inferred = extractActiveMemoryDefaults({
+            preferences,
+            staticFacts: [
+                ...staticFacts,
+                ...dynamicFacts,
+                ...relevantMemories.map((m) => `${m.title}: ${m.snippet}`),
+            ],
+        });
+        if (Object.keys(inferred.activeDefaults).length > 0) {
+            promptLines.push(`Active Memory Defaults: ${Object.entries(inferred.activeDefaults)
+                .map(([k, v]) => `${k}=${String(v)}`)
+                .join(", ")}`);
+            mdLines.push("### Active Defaults (Auto-Fill)", ...Object.entries(inferred.activeDefaults).map(([k, v]) => `- **${k}**: \`${String(v)}\``));
+        }
+        return {
+            enabled: true,
+            namespace,
+            fundingSource,
+            staticFacts,
+            dynamicContext: dynamicFacts,
+            recalledMemories: relevantMemories,
+            formattedPromptContext: promptLines.join("\n"),
+            profileMarkdown: mdLines.join("\n"),
+            profile: {
+                static: staticFacts,
+                dynamic: dynamicFacts,
+                preferences,
+            },
+            relevantMemories,
+            activeDefaults: inferred.activeDefaults,
+            activeGuardrails: inferred.activeGuardrails,
+        };
+    }
+    /**
+     * Stores a governed, secret-sanitized document/memory in the workspace's Supermemory v5 namespace
+     * with `dreaming: "instant"` so profile facts are synthesized immediately.
+     */
+    async addMemory(params) {
+        const namespace = this.namespaceForWorkspace(params.workspaceId);
+        const sanitizedContent = this.sanitizeContent(params.content);
+        const docId = params.documentId || `mem_${crypto.randomBytes(8).toString("hex")}`;
+        const { client, fundingSource } = this.resolveClient(params.apiKeyOverride);
+        if (!client) {
+            return {
+                documentId: docId,
+                namespace,
+                status: "local_only",
+                sanitizedContent,
+                fundingSource,
+            };
+        }
+        const res = await this.withTimeout(() => client.add(namespace, {
+            id: docId,
+            content: `${params.title}\n\n${sanitizedContent}`,
+            taskType: "memory",
+            dreaming: params.dreaming || "instant",
+            metadata: {
+                title: params.title,
+                muxoWorkspaceId: params.workspaceId,
+                muxoKind: params.kind,
+                ...(params.metadata || {}),
+            },
+        }), 1500);
+        return {
+            documentId: String(res?.id || docId),
+            namespace,
+            status: String(res?.status || "queued"),
+            sanitizedContent,
+            fundingSource,
+        };
+    }
+    async recordExecutionMemory(params) {
+        try {
+            const added = await this.addMemory({
+                workspaceId: params.workspaceId,
+                title: `Execution: ${params.toolSlug} (${params.status})`,
+                content: params.summary,
+                kind: "execution_outcome",
+                apiKeyOverride: params.apiKeyOverride,
+                metadata: {
+                    toolSlug: params.toolSlug,
+                    lane: params.lane,
+                    riskLevel: params.riskLevel,
+                    status: params.status,
+                },
+            });
+            return added ? added.documentId : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Deletes/forgets a memory document from the workspace's Supermemory v5 namespace.
+     */
+    async deleteMemory(workspaceId, documentId, apiKeyOverride) {
+        const namespace = this.namespaceForWorkspace(workspaceId);
+        const { client } = this.resolveClient(apiKeyOverride);
+        if (!client) {
+            return { deleted: true, namespace };
+        }
+        try {
+            const res = await this.withTimeout(() => client.documents.delete(namespace, {
+                ids: [documentId],
+            }), 1200);
+            return {
+                deleted: (res?.count || 0) >= 1,
+                namespace,
+            };
+        }
+        catch {
+            return { deleted: false, namespace };
+        }
+    }
+    /**
+     * Semantically searches and forgets/prunes outdated memories in Supermemory v5 matching a query.
+     */
+    async forgetMatching(params) {
+        const namespace = this.namespaceForWorkspace(params.workspaceId);
+        const { client, fundingSource } = this.resolveClient(params.apiKeyOverride);
+        if (!client || !params.query.trim()) {
+            return {
+                namespace,
+                deletedRemoteIds: [],
+                fundingSource,
+            };
+        }
+        try {
+            const searchRes = await this.withTimeout(() => client.search(namespace, {
+                query: params.query.trim(),
+                limit: Math.min(10, Math.max(1, Number(params.limit || 5))),
+                searchMode: "hybrid",
+                include: { documents: true, forgotten: false, related: false },
+                rewriteQuery: false,
+            }), 1200);
+            const docIds = Array.from(new Set((searchRes?.results || [])
+                .map((r) => String(r.included?.document?.id || r.id || ""))
+                .filter(Boolean)));
+            if (docIds.length > 0) {
+                await this.withTimeout(() => client.documents.delete(namespace, { ids: docIds }), 1200);
+                return {
+                    namespace,
+                    deletedRemoteIds: docIds,
+                    fundingSource,
+                };
+            }
+        }
+        catch {
+            // Fail-open on remote pruning errors
+        }
+        return {
+            namespace,
+            deletedRemoteIds: [],
+            fundingSource,
+        };
+    }
+}
+export function extractActiveMemoryDefaults(params) {
+    const activeDefaults = {};
+    const activeGuardrails = [];
+    const activeFacts = (params.temporalFacts || []).filter((f) => f.validTo === null);
+    for (const fact of activeFacts) {
+        const subj = String(fact.subject || "").toLowerCase();
+        const pred = String(fact.predicate || "").toLowerCase();
+        const obj = String(fact.object || "").trim();
+        if (!obj)
+            continue;
+        if (subj === "workspace_guardrail" || pred === "enforces_rule") {
+            if (!activeGuardrails.includes(obj))
+                activeGuardrails.push(obj);
+            continue;
+        }
+        if ((subj.includes("region") || pred.includes("region")) &&
+            !activeDefaults.defaultRegion) {
+            const regToken = obj.match(/\b((?:aws-)?(?:us|eu|ap|sa|ca|me|af)-(?:east|west|central|north|south|northeast|southeast)-[1-9])\b/i);
+            if (regToken) {
+                activeDefaults.defaultRegion = regToken[1].toLowerCase();
+            }
+            else if (!/\s/.test(obj)) {
+                activeDefaults.defaultRegion = obj;
+            }
+        }
+        if ((subj.includes("github") || subj.includes("repo") || pred.includes("repo")) &&
+            obj.includes("/") &&
+            !activeDefaults.defaultGithubFullRepo) {
+            const [owner, repo] = obj.split("/");
+            if (owner && repo) {
+                activeDefaults.defaultGithubOwner = owner.trim();
+                activeDefaults.defaultGithubRepo = repo.trim();
+                activeDefaults.defaultGithubFullRepo = `${owner.trim()}/${repo.trim()}`;
+            }
+        }
+        if ((subj.includes("slack") || pred.includes("channel")) &&
+            !activeDefaults.defaultSlackChannel) {
+            activeDefaults.defaultSlackChannel = obj.replace(/^#/, "").trim();
+        }
+        if ((subj.includes("email") || pred.includes("email")) &&
+            obj.includes("@") &&
+            !activeDefaults.defaultEmail) {
+            activeDefaults.defaultEmail = obj;
+        }
+        if ((subj.includes("domain") || pred.includes("domain")) &&
+            !activeDefaults.defaultDomain) {
+            activeDefaults.defaultDomain = obj.replace(/^https?:\/\//i, "").replace(/\/.*$/, "");
+        }
+    }
+    const textCorpus = [
+        ...(params.memories || []).map((m) => `${m.title}: ${m.content}`),
+        ...(params.preferences || []),
+        ...(params.staticFacts || []),
+    ];
+    for (const rawText of textCorpus) {
+        const text = String(rawText || "");
+        if (!activeDefaults.defaultRegion) {
+            const regMatch = text.match(/\b((?:aws-)?(?:us|eu|ap|sa|ca|me|af)-(?:east|west|central|north|south|northeast|southeast)-[1-9])\b/i);
+            if (regMatch) {
+                activeDefaults.defaultRegion = regMatch[1].toLowerCase();
+            }
+        }
+        if (!activeDefaults.defaultGithubFullRepo) {
+            const repoMatch = text.match(/(?:default\s+(?:github\s+)?repo(?:sitory)?|github\s+repo(?:sitory)?|primary\s+repo(?:sitory)?|repo\s+is)\s*(?:is|:|=)?\s*["'`]?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)["'`]?/i) ||
+                text.match(/\bgithub\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\b/i);
+            if (repoMatch) {
+                const [owner, repo] = repoMatch[1].split("/");
+                if (owner && repo) {
+                    activeDefaults.defaultGithubOwner = owner;
+                    activeDefaults.defaultGithubRepo = repo;
+                    activeDefaults.defaultGithubFullRepo = `${owner}/${repo}`;
+                }
+            }
+        }
+        if (!activeDefaults.defaultSlackChannel) {
+            const slackMatch = text.match(/(?:default\s+(?:slack\s+)?channel|slack\s+channel|post\s+to\s+channel)\s*(?:is|:|=)?\s*#?([a-z0-9_-]{2,40})\b/i) || text.match(/\B#([a-z][a-z0-9_-]{2,35})\b/);
+            if (slackMatch) {
+                activeDefaults.defaultSlackChannel = slackMatch[1].toLowerCase();
+            }
+        }
+        if (!activeDefaults.defaultEmail) {
+            const emailMatch = text.match(/(?:default\s+(?:recipient\s+|alert\s+)?email|send\s+emails?\s+to|notify\s+email|recipient_email)\s*(?:is|:|=)?\s*([A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})/i);
+            if (emailMatch) {
+                activeDefaults.defaultEmail = emailMatch[1];
+            }
+        }
+        if (!activeDefaults.defaultDomain) {
+            const domainMatch = text.match(/(?:default\s+domain|primary\s+domain|company\s+domain)\s*(?:is|:|=)?\s*(?:https?:\/\/)?([a-z0-9.-]+\.[a-z]{2,})\b/i);
+            if (domainMatch) {
+                activeDefaults.defaultDomain = domainMatch[1].toLowerCase();
+            }
+        }
+        if (/workspace\s+guardrail/i.test(text)) {
+            const cleaned = text.replace(/^.*?Workspace Guardrail:\s*/i, "").trim();
+            if (cleaned && !activeGuardrails.includes(cleaned)) {
+                activeGuardrails.push(cleaned);
+            }
+        }
+    }
+    return {
+        activeDefaults,
+        activeGuardrails,
+    };
+}
+export function applyActiveMemoryToToolInput(params) {
+    const mergedInput = { ...(params.input || {}) };
+    const autoFilledInput = {};
+    const explanations = [];
+    const defaults = params.activeDefaults || {};
+    const slug = String(params.toolSlug || "").toLowerCase();
+    // 1. Cloud provisioning tools: auto-fill region if not explicitly provided
+    if (slug.startsWith("resource.") && defaults.defaultRegion) {
+        if (!mergedInput.region || String(mergedInput.region).trim() === "") {
+            mergedInput.region = defaults.defaultRegion;
+            autoFilledInput.region = defaults.defaultRegion;
+            explanations.push(`Auto-filled region="${defaults.defaultRegion}" from Supermemory`);
+        }
+    }
+    // 2. GitHub tools: auto-fill owner & repo if missing or generic placeholder
+    if ((slug.startsWith("app.github.") || slug === "instant.github.repo_intel") &&
+        defaults.defaultGithubOwner &&
+        defaults.defaultGithubRepo) {
+        const isGenericPlaceholder = mergedInput.owner === "muxo-ai" && mergedInput.repo === "platform";
+        if (!mergedInput.owner || isGenericPlaceholder) {
+            mergedInput.owner = defaults.defaultGithubOwner;
+            autoFilledInput.owner = defaults.defaultGithubOwner;
+        }
+        if (!mergedInput.repo || isGenericPlaceholder) {
+            mergedInput.repo = defaults.defaultGithubRepo;
+            autoFilledInput.repo = defaults.defaultGithubRepo;
+        }
+        if (autoFilledInput.owner || autoFilledInput.repo) {
+            explanations.push(`Auto-filled GitHub repo "${defaults.defaultGithubOwner}/${defaults.defaultGithubRepo}" from Supermemory`);
+        }
+    }
+    // 3. Slack tools: auto-fill channel if missing or generic placeholder ("general")
+    if (slug.startsWith("app.slack.") && defaults.defaultSlackChannel) {
+        if (!mergedInput.channel || mergedInput.channel === "general") {
+            mergedInput.channel = defaults.defaultSlackChannel;
+            autoFilledInput.channel = defaults.defaultSlackChannel;
+            explanations.push(`Auto-filled Slack channel "#${defaults.defaultSlackChannel}" from Supermemory`);
+        }
+    }
+    // 4. Gmail send_email: auto-fill recipient_email if missing or placeholder
+    if (slug === "app.gmail.send_email" && defaults.defaultEmail) {
+        if (!mergedInput.recipient_email ||
+            mergedInput.recipient_email === "team@example.com") {
+            mergedInput.recipient_email = defaults.defaultEmail;
+            autoFilledInput.recipient_email = defaults.defaultEmail;
+            explanations.push(`Auto-filled recipient_email="${defaults.defaultEmail}" from Supermemory`);
+        }
+    }
+    // 5. DNS / Domain tools: auto-fill domain if missing or example.com
+    if ((slug === "instant.dns.resolve" || slug === "instant.dns.lookup") &&
+        defaults.defaultDomain) {
+        if (!mergedInput.domain || mergedInput.domain === "example.com") {
+            mergedInput.domain = defaults.defaultDomain;
+            autoFilledInput.domain = defaults.defaultDomain;
+            explanations.push(`Auto-filled domain="${defaults.defaultDomain}" from Supermemory`);
+        }
+    }
+    // 6. SEO / Web tools: auto-fill url from defaultDomain if missing or generic placeholder
+    if ((slug === "instant.seo.audit" ||
+        slug === "instant.web.scrape" ||
+        slug === "instant.web.crawl") &&
+        defaults.defaultDomain) {
+        if (!mergedInput.url ||
+            mergedInput.url === "https://example.com") {
+            const normalizedUrl = defaults.defaultDomain.startsWith("http")
+                ? defaults.defaultDomain
+                : `https://${defaults.defaultDomain}`;
+            mergedInput.url = normalizedUrl;
+            autoFilledInput.url = normalizedUrl;
+            explanations.push(`Auto-filled url="${normalizedUrl}" from Supermemory`);
+        }
+    }
+    return {
+        mergedInput,
+        autoFilledInput,
+        explanations,
+    };
+}
+export function parseNaturalLanguageMemoryInstruction(prompt) {
+    const cleanPrompt = String(prompt || "").trim();
+    const isMemoryInstruction = /^(?:hey\s+muxo[,:\s]*)?(?:please\s+)?(?:remember(?:\s+that)?|save\s+to\s+memory|store\s+in\s+memory|note\s+that|set\s+(?:our\s+|my\s+)?default|our\s+default\s+(?:github\s+repo|repo|region|slack\s+channel|email|domain)\s+is|my\s+default\s+(?:github\s+repo|repo|region|slack\s+channel|email|domain)\s+is)\b/i.test(cleanPrompt);
+    const normalizedBody = cleanPrompt
+        .replace(/^(?:hey\s+muxo[,:\s]*)?(?:please\s+)?(?:remember(?:\s+that)?|save\s+to\s+memory|store\s+in\s+memory|note\s+that)[:\s]*/i, "")
+        .trim();
+    const { activeDefaults } = extractActiveMemoryDefaults({
+        preferences: [cleanPrompt],
+        staticFacts: [normalizedBody],
+    });
+    const temporalFacts = [];
+    const learnedParts = [];
+    if (activeDefaults.defaultRegion) {
+        temporalFacts.push({
+            subject: "workspace:default_region",
+            predicate: "prefers_region",
+            object: activeDefaults.defaultRegion,
+            summary: `Default cloud region is ${activeDefaults.defaultRegion}`,
+        });
+        learnedParts.push(`default cloud region = ${activeDefaults.defaultRegion}`);
+    }
+    if (activeDefaults.defaultGithubFullRepo) {
+        temporalFacts.push({
+            subject: "workspace:default_github_repo",
+            predicate: "prefers_repo",
+            object: activeDefaults.defaultGithubFullRepo,
+            summary: `Default GitHub repository is ${activeDefaults.defaultGithubFullRepo}`,
+        });
+        learnedParts.push(`default GitHub repo = ${activeDefaults.defaultGithubFullRepo}`);
+    }
+    if (activeDefaults.defaultSlackChannel) {
+        temporalFacts.push({
+            subject: "workspace:default_slack_channel",
+            predicate: "prefers_channel",
+            object: activeDefaults.defaultSlackChannel,
+            summary: `Default Slack channel is #${activeDefaults.defaultSlackChannel}`,
+        });
+        learnedParts.push(`default Slack channel = #${activeDefaults.defaultSlackChannel}`);
+    }
+    if (activeDefaults.defaultEmail) {
+        temporalFacts.push({
+            subject: "workspace:default_email",
+            predicate: "prefers_email",
+            object: activeDefaults.defaultEmail,
+            summary: `Default notification email is ${activeDefaults.defaultEmail}`,
+        });
+        learnedParts.push(`default email = ${activeDefaults.defaultEmail}`);
+    }
+    if (activeDefaults.defaultDomain) {
+        temporalFacts.push({
+            subject: "workspace:default_domain",
+            predicate: "prefers_domain",
+            object: activeDefaults.defaultDomain,
+            summary: `Default workspace domain is ${activeDefaults.defaultDomain}`,
+        });
+        learnedParts.push(`default domain = ${activeDefaults.defaultDomain}`);
+    }
+    if (temporalFacts.length === 0 && isMemoryInstruction && normalizedBody) {
+        temporalFacts.push({
+            subject: "workspace:operator_preference",
+            predicate: "remembers",
+            object: normalizedBody.slice(0, 140),
+            summary: normalizedBody.slice(0, 180),
+        });
+    }
+    const title = learnedParts.length > 0
+        ? `Learned Default: ${learnedParts.join(", ").slice(0, 80)}`
+        : `Remembered Preference: ${(normalizedBody || cleanPrompt).slice(0, 72)}`;
+    const humanSummary = learnedParts.length > 0
+        ? `Remembered in Supermemory and enabled auto-fill for: ${learnedParts.join(" · ")}.`
+        : `Saved to Supermemory: "${normalizedBody || cleanPrompt}"`;
+    return {
+        isMemoryInstruction,
+        title,
+        content: normalizedBody || cleanPrompt,
+        kind: "preference",
+        extractedDefaults: activeDefaults,
+        temporalFacts,
+        humanSummary,
+    };
+}
+export function explainMemoryContext(params) {
+    const mem = params.memory;
+    const defaultsEntries = Object.entries(mem.activeDefaults || {});
+    const defaultsPlain = defaultsEntries.length > 0
+        ? `Learned defaults active (${defaultsEntries.map(([k, v]) => `${k}: ${String(v)}`).join(", ")}) and automatically fill into matching tool calls.`
+        : "No learned defaults set yet (say 'Remember our default region is us-east-1' or 'Remember our default repo is owner/repo' to set one).";
+    const factsCount = (mem.staticFacts?.length || 0) +
+        (mem.dynamicContext?.length || 0) +
+        (params.localCount || 0);
+    const scanSafe = mem.contextPoisoningScan?.safe !== false;
+    const headline = defaultsEntries.length > 0
+        ? `Muxo Memory active with ${defaultsEntries.length} auto-fill default${defaultsEntries.length === 1 ? "" : "s"} and ${factsCount} stored workspace item${factsCount === 1 ? "" : "s"}.`
+        : `Muxo Memory active with ${factsCount} stored workspace item${factsCount === 1 ? "" : "s"}.`;
+    const nonTechnical = [
+        headline,
+        defaultsPlain,
+        mem.recalledMemories && mem.recalledMemories.length > 0
+            ? `Recalled ${mem.recalledMemories.length} relevant memory note${mem.recalledMemories.length === 1 ? "" : "s"} for this context.`
+            : "All stored memories are secret-scrubbed so API keys and passwords are never saved.",
+        scanSafe
+            ? "Memory safety check: Clean (no prompt-injection or poisoning patterns detected)."
+            : `Memory safety warning: ${mem.contextPoisoningScan?.findingsCount || 1} suspicious pattern(s) flagged (${mem.contextPoisoningScan?.riskLevel || "medium"}).`,
+    ].join(" ");
+    const technical = `namespace=${mem.namespace} | enabled=${mem.enabled} | fundingSource=${mem.fundingSource || "local_fallback"} | staticFacts=${mem.staticFacts?.length || 0} | dynamicContext=${mem.dynamicContext?.length || 0} | recalledMemories=${mem.recalledMemories?.length || 0} | localRecords=${params.localCount ?? 0} | temporalGraph=(active=${params.activeTemporalCount ?? (mem.temporalFacts?.length || 0)}, superseded=${params.historicalTemporalCount ?? 0}) | activeDefaults=${JSON.stringify(mem.activeDefaults || {})} | contextPoisoning=(safe=${scanSafe}, risk=${mem.contextPoisoningScan?.riskLevel || "none"}, findings=${mem.contextPoisoningScan?.findingsCount || 0})`;
+    return formatHumanFriendlyExplanation({
+        headline,
+        nonTechnical,
+        technical,
+        policy: params.policy,
+        languageMode: params.languageMode,
+    });
+}
+/**
+ * Deterministic 64-dimensional semantic feature-hashing embedding vector
+ * compatible with Cloudflare Vectorize / Workers AI (`@cf/baai/bge-base-en-v1.5`) hybrid recall.
+ */
+export function computeSemanticEmbedding(text, dimensions = 64) {
+    const vec = new Array(dimensions).fill(0);
+    const normalized = String(text || "")
+        .toLowerCase()
+        .replace(/[^a-z0-9_./#@-\s]/g, " ");
+    const tokens = normalized
+        .split(/\s+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length >= 2);
+    if (tokens.length === 0)
+        return vec;
+    // Semantic concept synonym expansion so related queries ("db"/"postgres", "mail"/"email", "repo"/"github") map to shared vector dimensions
+    const expandedTokens = [...tokens];
+    for (const tok of tokens) {
+        if (/^(postgres|postgresql|neon|supabase|sql|db|database)$/.test(tok)) {
+            expandedTokens.push("concept_database", "concept_postgres");
+        }
+        if (/^(redis|upstash|cache|kv)$/.test(tok)) {
+            expandedTokens.push("concept_cache", "concept_redis");
+        }
+        if (/^(repo|repository|github|git|pr|issue)$/.test(tok)) {
+            expandedTokens.push("concept_github", "concept_repo");
+        }
+        if (/^(region|us-east-1|us-west-2|eu-central-1|zone|datacenter)$/.test(tok)) {
+            expandedTokens.push("concept_region", "concept_cloud");
+        }
+        if (/^(slack|channel|chat|alert|incident)$/.test(tok)) {
+            expandedTokens.push("concept_slack", "concept_messaging");
+        }
+        if (/^(email|gmail|inbox|recipient|mail)$/.test(tok)) {
+            expandedTokens.push("concept_email", "concept_communication");
+        }
+    }
+    for (let i = 0; i < expandedTokens.length; i++) {
+        const feature = expandedTokens[i];
+        const digest = crypto.createHash("md5").update(feature).digest();
+        const dimIdx = digest[0] % dimensions;
+        const sign = (digest[1] & 1) === 0 ? 1 : -1;
+        const weight = feature.startsWith("concept_") ? 1.5 : 1.0;
+        vec[dimIdx] += sign * weight;
+        // Character trigram projection for sub-word resilience
+        for (let c = 0; c <= feature.length - 3; c++) {
+            const tri = feature.slice(c, c + 3);
+            const triDigest = crypto.createHash("md5").update(`tri:${tri}`).digest();
+            const triIdx = triDigest[0] % dimensions;
+            const triSign = (triDigest[1] & 1) === 0 ? 0.35 : -0.35;
+            vec[triIdx] += triSign;
+        }
+    }
+    const norm = Math.sqrt(vec.reduce((acc, v) => acc + v * v, 0));
+    if (norm > 0) {
+        for (let d = 0; d < dimensions; d++) {
+            vec[d] = Number((vec[d] / norm).toFixed(6));
+        }
+    }
+    return vec;
+}
+export function cosineSimilarity(vecA, vecB) {
+    const len = Math.min(vecA.length, vecB.length);
+    if (len === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < len; i++) {
+        dot += vecA[i] * vecB[i];
+        normA += vecA[i] * vecA[i];
+        normB += vecB[i] * vecB[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return Math.max(0, Math.min(1, dot / (Math.sqrt(normA) * Math.sqrt(normB))));
+}
+export function rankMemoriesHybrid(params) {
+    const q = String(params.query || "").trim();
+    const qVec = computeSemanticEmbedding(q);
+    const qTokens = q
+        .toLowerCase()
+        .split(/[^a-z0-9_./#@-]+/)
+        .filter((t) => t.length >= 2);
+    const nowMs = Date.now();
+    const scored = (params.memories || []).map((mem) => {
+        const corpus = `${mem.title} ${mem.content} ${mem.kind}`;
+        const docVec = computeSemanticEmbedding(corpus);
+        const vectorSim = q ? cosineSimilarity(qVec, docVec) : 0.5;
+        const lowerCorpus = corpus.toLowerCase();
+        const matchedTokens = qTokens.length > 0
+            ? qTokens.filter((tok) => lowerCorpus.includes(tok)).length
+            : 1;
+        const lexicalOverlap = qTokens.length > 0 ? matchedTokens / qTokens.length : 0.5;
+        const ageHours = Math.max(0, (nowMs - new Date(mem.createdAt || nowMs).getTime()) / 3_600_000);
+        const recencyWeight = 1 / (1 + ageHours / 168); // 1-week half-life
+        const hybridScore = Number((0.5 * vectorSim + 0.35 * lexicalOverlap + 0.15 * recencyWeight).toFixed(4));
+        return {
+            ...mem,
+            hybridScore,
+            vectorSimilarity: Number(vectorSim.toFixed(4)),
+            lexicalOverlap: Number(lexicalOverlap.toFixed(4)),
+        };
+    });
+    scored.sort((a, b) => b.hybridScore - a.hybridScore);
+    const limit = Math.max(1, Math.min(50, params.limit || 10));
+    const top = scored.slice(0, limit);
+    return {
+        rankedMemories: top,
+        vectorDimensions: 64,
+        embeddingModel: "@cf/baai/bge-base-en-v1.5 (cloudflare-vectorize-hybrid)",
+        topScore: top[0]?.hybridScore || 0,
+    };
+}