@muxoai/sdk 1.2.3 → 1.4.2

package/dist/providers/supermemory.d.ts

@@ -0,0 +1,160 @@
+import type { MuxoConfig } from "../config.js";
+import type { GovernancePolicy, HumanFriendlyExplanation, LanguageMode, MemoryContextSummary, MemoryRecordKind, TemporalGraphFact, WorkspaceMemoryRecord } from "../types.js";
+/**
+ * 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 declare class SupermemoryAdapter {
+    private readonly config;
+    private readonly client;
+    private readonly byokClients;
+    private unavailableUntil;
+    constructor(config: MuxoConfig);
+    private resolveClient;
+    private withTimeout;
+    isEnabled(apiKeyOverride?: string | null): boolean;
+    /**
+     * Derives a strict Supermemory v5 namespace (`^[a-zA-Z0-9_:-]+$`) scoped to a workspace.
+     */
+    namespaceForWorkspace(workspaceId: string): string;
+    getWorkspaceNamespace(workspaceId: string): string;
+    /**
+     * 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: string): string;
+    /**
+     * 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`.
+     */
+    getContextForWorkspace(workspaceIdOrParams: string | {
+        workspaceId: string;
+        query?: string;
+        limit?: number;
+        apiKeyOverride?: string | null;
+    }, optionalQuery?: string, optionalApiKeyOverride?: string | null): Promise<MemoryContextSummary>;
+    /**
+     * Stores a governed, secret-sanitized document/memory in the workspace's Supermemory v5 namespace
+     * with `dreaming: "instant"` so profile facts are synthesized immediately.
+     */
+    addMemory(params: {
+        workspaceId: string;
+        documentId?: string;
+        title: string;
+        content: string;
+        kind: MemoryRecordKind;
+        metadata?: Record<string, unknown>;
+        apiKeyOverride?: string | null;
+        dreaming?: "auto" | "instant";
+    }): Promise<{
+        documentId: string;
+        namespace: string;
+        status: string;
+        sanitizedContent: string;
+        fundingSource: "muxo_funded" | "customer_byok_supermemory" | "local_fallback";
+    }>;
+    recordExecutionMemory(params: {
+        workspaceId: string;
+        toolSlug: string;
+        lane: string;
+        riskLevel: string;
+        reason: string;
+        status: string;
+        summary: string;
+        apiKeyOverride?: string | null;
+    }): Promise<string | null>;
+    /**
+     * Deletes/forgets a memory document from the workspace's Supermemory v5 namespace.
+     */
+    deleteMemory(workspaceId: string, documentId: string, apiKeyOverride?: string | null): Promise<{
+        deleted: boolean;
+        namespace: string;
+    }>;
+    /**
+     * Semantically searches and forgets/prunes outdated memories in Supermemory v5 matching a query.
+     */
+    forgetMatching(params: {
+        workspaceId: string;
+        query: string;
+        limit?: number;
+        apiKeyOverride?: string | null;
+    }): Promise<{
+        namespace: string;
+        deletedRemoteIds: string[];
+        fundingSource: "muxo_funded" | "customer_byok_supermemory" | "local_fallback";
+    }>;
+}
+export interface ActiveMemoryDefaults {
+    defaultRegion?: string;
+    defaultGithubOwner?: string;
+    defaultGithubRepo?: string;
+    defaultGithubFullRepo?: string;
+    defaultSlackChannel?: string;
+    defaultEmail?: string;
+    defaultDomain?: string;
+    defaultUrl?: string;
+    defaultPlan?: string;
+    [key: string]: unknown;
+}
+export declare function extractActiveMemoryDefaults(params: {
+    memories?: WorkspaceMemoryRecord[];
+    temporalFacts?: TemporalGraphFact[];
+    preferences?: string[];
+    staticFacts?: string[];
+}): {
+    activeDefaults: ActiveMemoryDefaults;
+    activeGuardrails: string[];
+};
+export declare function applyActiveMemoryToToolInput(params: {
+    toolSlug: string;
+    input: Record<string, unknown>;
+    activeDefaults?: ActiveMemoryDefaults;
+}): {
+    mergedInput: Record<string, unknown>;
+    autoFilledInput: Record<string, unknown>;
+    explanations: string[];
+};
+export declare function parseNaturalLanguageMemoryInstruction(prompt: string): {
+    isMemoryInstruction: boolean;
+    title: string;
+    content: string;
+    kind: MemoryRecordKind;
+    extractedDefaults: ActiveMemoryDefaults;
+    temporalFacts: Array<{
+        subject: string;
+        predicate: string;
+        object: string;
+        summary: string;
+    }>;
+    humanSummary: string;
+};
+export declare function explainMemoryContext(params: {
+    memory: MemoryContextSummary;
+    localCount?: number;
+    activeTemporalCount?: number;
+    historicalTemporalCount?: number;
+    policy?: Partial<GovernancePolicy> | null;
+    languageMode?: LanguageMode;
+}): HumanFriendlyExplanation;
+/**
+ * Deterministic 64-dimensional semantic feature-hashing embedding vector
+ * compatible with Cloudflare Vectorize / Workers AI (`@cf/baai/bge-base-en-v1.5`) hybrid recall.
+ */
+export declare function computeSemanticEmbedding(text: string, dimensions?: number): number[];
+export declare function cosineSimilarity(vecA: number[], vecB: number[]): number;
+export declare function rankMemoriesHybrid(params: {
+    query: string;
+    memories: WorkspaceMemoryRecord[];
+    temporalFacts?: TemporalGraphFact[];
+    limit?: number;
+}): {
+    rankedMemories: Array<WorkspaceMemoryRecord & {
+        hybridScore: number;
+        vectorSimilarity: number;
+        lexicalOverlap: number;
+    }>;
+    vectorDimensions: number;
+    embeddingModel: string;
+    topScore: number;
+};