qlogicagent 2.13.4 → 2.13.5

package/dist/skills/memory/local-embedding.js

@@ -0,0 +1,210 @@
+/**
+ * Local Embedding — Pluggable embedding interface for local memory.
+ *
+ * Provides a unified interface for text → vector embedding.
+ * If no API config is provided, memory search falls back to FTS-only.
+ */
+// ── Null Embedding (FTS-only fallback) ──────────────────────
+export class NullEmbeddingProvider {
+    dimensions = 0;
+    model = "none";
+    async embed(_text) {
+        return new Float32Array(0);
+    }
+    async embedBatch(_texts) {
+        return _texts.map(() => new Float32Array(0));
+    }
+}
+// ── API-based Embedding ─────────────────────────────────────
+export class ApiEmbeddingProvider {
+    dimensions;
+    model;
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    format;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.apiKey = config.apiKey;
+        this.model = config.model;
+        this.dimensions = config.dimensions ?? 1536;
+        this.timeoutMs = config.timeoutMs ?? 10_000;
+        this.format = config.format ?? "openai";
+    }
+    async embed(text) {
+        const results = await this.embedBatch([text]);
+        return results[0];
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const { url, body } = this.buildRequest(texts);
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errBody = await response.text().catch(() => "");
+                throw new Error(`Embedding API error [${this.format}]: ${response.status} ${response.statusText}${errBody ? ` — ${errBody.slice(0, 200)}` : ""}`);
+            }
+            const json = await response.json();
+            return this.parseResponse(json, texts.length);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    // ── Format-specific request builders ─────────────────
+    buildRequest(texts) {
+        switch (this.format) {
+            case "minimax":
+                return {
+                    url: `${this.baseUrl}/v1/embeddings`,
+                    body: { model: this.model, texts, type: "db" },
+                };
+            case "volcengine":
+                // Volcengine multimodal embedding — one call per text (single-input API)
+                // For batch, we call once with first text. True batching handled at embedBatch level.
+                return {
+                    url: `${this.baseUrl}/v1/embeddings/multimodal`,
+                    body: {
+                        model: this.model,
+                        input: texts.map((t) => ({ type: "text", text: t })),
+                        dimensions: this.dimensions,
+                    },
+                };
+            default: { // "openai"
+                // baseUrl 已含版本段(如 zhipu .../paas/v4、openai .../v1)→ 直接拼 /embeddings;
+                // 否则补 /v1/embeddings。避免 .../v4/v1/embeddings 双版本 404。
+                const url = /\/v\d+$/.test(this.baseUrl)
+                    ? `${this.baseUrl}/embeddings`
+                    : `${this.baseUrl}/v1/embeddings`;
+                return {
+                    url,
+                    body: { model: this.model, input: texts, dimensions: this.dimensions },
+                };
+            }
+        }
+    }
+    // ── Format-specific response parsers ─────────────────
+    parseResponse(json, expectedCount) {
+        switch (this.format) {
+            case "minimax": {
+                // MiniMax: { vectors: number[][] }
+                const vectors = json.vectors;
+                if (!vectors || vectors.length === 0) {
+                    throw new Error("MiniMax embedding returned empty vectors");
+                }
+                return vectors.map((v) => new Float32Array(v));
+            }
+            case "volcengine": {
+                // Volcengine multimodal: { data: { embedding: number[] } } (single)
+                // or { data: [{ embedding: number[] }] } (array)
+                const data = json.data;
+                if (Array.isArray(data)) {
+                    return data.map((d) => new Float32Array(d.embedding));
+                }
+                // Single object response
+                if (data?.embedding) {
+                    return [new Float32Array(data.embedding)];
+                }
+                throw new Error("Volcengine embedding returned unexpected structure");
+            }
+            default: {
+                // OpenAI standard: { data: [{ embedding: number[], index: number }] }
+                const items = json.data;
+                if (!items || items.length === 0) {
+                    throw new Error("OpenAI embedding returned empty data");
+                }
+                const sorted = items.sort((a, b) => a.index - b.index);
+                return sorted.map((d) => new Float32Array(d.embedding));
+            }
+        }
+    }
+}
+/**
+ * Create an embedding provider based on configuration.
+ *
+ * Resolution order:
+ *   1. API config → ApiEmbeddingProvider
+ *   2. No API config → NullEmbeddingProvider (FTS-only)
+ */
+export function createEmbeddingProvider(config) {
+    if (config?.api) {
+        return new ApiEmbeddingProvider(config.api);
+    }
+    return new NullEmbeddingProvider();
+}
+// ── Provider Format Resolution ──────────────────────────────
+/**
+ * Known provider → format mapping.
+ * Used only for the explicit ModelRegistry embedding binding.
+ */
+export const PROVIDER_EMBEDDING_REGISTRY = {
+    qwen: {
+        format: "openai",
+        baseUrl: "https://dashscope.aliyuncs.com/compatible-mode",
+        defaultModel: "text-embedding-v3",
+        defaultDimensions: 1024,
+    },
+    zhipu: {
+        format: "openai",
+        baseUrl: "https://open.bigmodel.cn/api/paas",
+        defaultModel: "embedding-3",
+        defaultDimensions: 2048,
+    },
+    minimax: {
+        format: "minimax",
+        baseUrl: "https://api.minimax.chat",
+        defaultModel: "embo-01",
+        defaultDimensions: 1024,
+    },
+    volcengine: {
+        format: "volcengine",
+        baseUrl: "https://ark.cn-beijing.volces.com/api",
+        defaultModel: "doubao-embedding-vision-251215",
+        defaultDimensions: 1024,
+    },
+    openai: {
+        format: "openai",
+        baseUrl: "https://api.openai.com",
+        defaultModel: "text-embedding-3-small",
+        defaultDimensions: 1536,
+    },
+    google: {
+        format: "openai",
+        baseUrl: "https://generativelanguage.googleapis.com",
+        defaultModel: "text-embedding-004",
+        defaultDimensions: 768,
+    },
+    deepseek: {
+        format: "openai",
+        baseUrl: "https://api.deepseek.com",
+        defaultModel: "text-embedding-v1",
+        defaultDimensions: 1024,
+    },
+};
+/**
+ * Resolve EmbeddingApiConfig from a known provider name + API key.
+ * Returns null if the provider has no known embedding endpoint.
+ */
+export function resolveProviderEmbeddingConfig(provider, apiKey, overrides) {
+    const entry = PROVIDER_EMBEDDING_REGISTRY[provider.toLowerCase()];
+    if (!entry)
+        return null;
+    return {
+        baseUrl: overrides?.baseUrl || entry.baseUrl,
+        apiKey,
+        model: overrides?.model || entry.defaultModel,
+        dimensions: overrides?.dimensions || entry.defaultDimensions,
+        format: entry.format,
+    };
+}

package/dist/skills/memory/local-memory-provider.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Local Memory Provider - implements MemoryProvider using local SQLite store.
+ *
+ * This is the default provider for desktop use. Requires no external service.
+ * Uses FTS5 for keyword search and optionally embedding API for vector search.
+ *
+ * Falls back gracefully:
+ *   - With embedding API configured: hybrid search (FTS + vector)
+ *   - Without embedding: FTS-only search (still useful for exact/keyword matches)
+ */
+import type { MemoryProvider, MemorySearchResult, MemorySearchOptions, MemoryIngestMessage, MemoryIngestOptions } from "../../protocol/wire/index.js";
+import type { MemoryClaimRecord, MemoryConflictRecord, MemoryUpdateInput, SqliteDatabase } from "./local-store.js";
+import { type AdoptedAttachment } from "./memory-attachment-store.js";
+import { type LocalEmbeddingConfig } from "./local-embedding.js";
+import { type ExtractedMemoryItem, type MemoryConsolidationResult } from "./memory-consolidation.js";
+export type { ExtractedMemoryItem } from "./memory-consolidation.js";
+export interface LocalMemoryProviderConfig {
+    /** Active owner profile. Determines the physical SQLite database location. */
+    ownerUserId?: string;
+    /** Embedding configuration. If omitted, uses FTS-only search. */
+    embedding?: LocalEmbeddingConfig;
+    /** User ID prefix for multi-tenant isolation. */
+    userIdPrefix?: string;
+    /** Factory function to create the SQLite database instance. */
+    createDatabase?: (dbPath: string) => SqliteDatabase;
+}
+export declare class LocalMemoryProvider implements MemoryProvider {
+    readonly providerId = "qmemory-local";
+    private store;
+    private embedding;
+    private consolidator;
+    private attachmentStore;
+    private userIdPrefix;
+    private dbPath;
+    constructor(config: LocalMemoryProviderConfig);
+    /** Persist an uploaded attachment (orphan until linked at commit). */
+    adoptAttachment(input: {
+        data?: Buffer;
+        sourceUrl?: string;
+        filename: string;
+        mimeType: string;
+        userId: string;
+    }): Promise<AdoptedAttachment>;
+    /** Resolve an attachment id to its on-disk path (for serving). */
+    locateAttachment(id: string): Promise<{
+        absPath: string;
+        mimeType: string;
+        filename: string;
+    } | null>;
+    /** Drop uploads that were never saved to a memory. */
+    purgeOrphanAttachments(): Promise<void>;
+    /** Read an attachment's bytes + mime (P2 multimodal understanding). */
+    readAttachmentBytes(id: string): Promise<{
+        bytes: Buffer;
+        mimeType: string;
+    } | null>;
+    /** Persist the understood/extracted text on an attachment row. */
+    setAttachmentText(id: string, text: string): void;
+    private resolveUserId;
+    private buildEmbedding;
+    search(query: string, userId: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
+    ingest(messages: MemoryIngestMessage[], userId: string, options?: MemoryIngestOptions): Promise<void>;
+    addText(text: string, userId: string, options?: MemoryIngestOptions & {
+        category?: string;
+        importance?: number;
+    }): Promise<{
+        memoriesAdded: number;
+    }>;
+    remove(memoryId: string): Promise<boolean>;
+    update(memoryId: string, input: MemoryUpdateInput): Promise<boolean>;
+    /**
+     * Commit extracted memory items through the single consolidation pipeline.
+     */
+    ingestExtracted(items: ExtractedMemoryItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationResult>;
+    observeExtracted(items: ExtractedMemoryItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationResult>;
+    proposeExtracted(items: ExtractedMemoryItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationResult>;
+    listClaims(userId: string): MemoryClaimRecord[];
+    listConflicts(userId: string): MemoryConflictRecord[];
+    /**
+     * Drain the consolidation backlog: auto-resolve open conflicts and promote
+     * corroborated pending claims. Called by dream after consolidation so the
+     * observation→proposal→claim pipeline doesn't accumulate unresolved state
+     * forever (the "proposals black hole").
+     *
+     * Conflict winner = higher source priority, then confidence, then recency.
+     * The loser claim is superseded and its backing memory archived.
+     */
+    resolveConflicts(userId: string, opts?: {
+        minEvidenceToPromote?: number;
+    }): Promise<{
+        conflictsResolved: number;
+        claimsPromoted: number;
+    }>;
+    /**
+     * Trigger memory decay - multi-strategy (temporal + staleness + noise).
+     * Also enforces capacity limit and runs vacuum for space reclamation.
+     */
+    triggerDecay(userId: string, _maxAgeDays?: number): Promise<{
+        decayed: number;
+    }>;
+    /**
+     * Apply feedback to a memory (useful/irrelevant/outdated/wrong).
+     * Adjusts importance or archives/deletes based on signal.
+     */
+    feedback(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
+        affected: number;
+    }>;
+    /**
+     * Get a user profile value.
+     */
+    getProfile(userId: string, key: string): string | null;
+    /**
+     * Set a user profile value (upsert).
+     */
+    setProfile(userId: string, key: string, value: string): void;
+    /**
+     * Get all profile entries for a user.
+     */
+    getAllProfiles(userId: string): Record<string, string>;
+    /**
+     * Delete a profile entry.
+     */
+    deleteProfile(userId: string, key: string): boolean;
+    /**
+     * Get memories within a time range, grouped by day.
+     * Powers "what happened last week" type queries.
+     */
+    getTemporalSlice(userId: string, startMs: number, endMs: number, options?: {
+        category?: string;
+        limit?: number;
+    }): {
+        date: string;
+        memories: Array<{
+            id: string;
+            text: string;
+            category: string;
+            importance: number;
+        }>;
+    }[];
+    /**
+     * Get activity summary over recent N days (daily counts + highlights).
+     */
+    getActivitySummary(userId: string, days?: number): {
+        dailyCounts: Array<{
+            date: string;
+            count: number;
+        }>;
+        highlights: Array<{
+            id: string;
+            text: string;
+            category: string;
+            importance: number;
+            date: string;
+        }>;
+    };
+    /**
+     * List full memory records for a user (paginated). Used by the memory atlas
+     * visualization, which needs the complete record shape (confidence, importance,
+     * accessCount, timestamps, tags) to drive its 3D rendering.
+     */
+    list(userId: string, options?: {
+        page?: number;
+        pageSize?: number;
+        activeOnly?: boolean;
+    }): import("./local-store.js").MemoryRecord[];
+    /**
+     * Find memories by event date (+/- tolerance). For temporal context retrieval.
+     */
+    /**
+     * Return the final atlas payload: a bounded interactive record window plus
+     * whole-history buckets/clusters for large timelines.
+     */
+    getAtlas(userId: string, options?: {
+        pageSize?: number;
+        windowStartAt?: number;
+        windowEndAt?: number;
+        windowCenterAt?: number;
+        bucketCount?: number;
+        clusterLimit?: number;
+        activeOnly?: boolean;
+    }): import("./local-store.js").MemoryAtlasResult;
+    findByEventDate(userId: string, targetDate: string, toleranceDays?: number): import("./local-store.js").MemorySearchHit[];
+    /**
+     * Find related memories (event continuity detection).
+     * Given a new memory, finds existing memories that are semantically related
+     * (cosine 0.6-0.82) and from the past 14 days. These represent continuations
+     * of an ongoing event/thread.
+     *
+     * Example: "interviewed with ByteDance on Monday" -> finds "sent ByteDance resume last week" -> linked event chain.
+     */
+    findRelatedEvents(text: string, userId: string, options?: {
+        maxDaysBack?: number;
+        minSimilarity?: number;
+        maxSimilarity?: number;
+        limit?: number;
+    }): Promise<Array<{
+        id: string;
+        text: string;
+        score: number;
+        date: string;
+    }>>;
+    /**
+     * Synthesize a temporal narrative from memories in a time range.
+     * Returns a structured timeline suitable for prompt injection.
+     */
+    synthesizeTimeline(userId: string, startMs: number, endMs: number): string;
+    /**
+     * Rerank search results by applying recency boost, access frequency,
+     * and importance weighting. No LLM needed - pure scoring heuristics.
+     *
+     * This goes beyond basic search scoring by considering:
+     *   - Temporal proximity (recent memories get boosted)
+     *   - Access frequency (frequently recalled = more relevant)
+     *   - Category alignment (if preferredCategories specified)
+     */
+    rerank(results: Array<{
+        id: string;
+        text: string;
+        score: number;
+        category?: string;
+        metadata?: Record<string, unknown>;
+    }>, options?: {
+        preferredCategories?: string[];
+        recencyBoostDays?: number;
+    }): Array<{
+        id: string;
+        text: string;
+        score: number;
+        category?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+    /**
+     * Health check - always healthy for local store.
+     */
+    health(): Promise<{
+        status: string;
+        memoryCount: number;
+        dbPath: string;
+    }>;
+    /**
+     * Get memory count for a user.
+     */
+    count(userId: string): number;
+    /**
+     * Reset all memories for a user.
+     */
+    resetUser(userId: string): Promise<number>;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+}
+/**
+ * Create a local memory provider (convenience factory).
+ * Caller must provide the createDatabase factory to avoid hard dependency on better-sqlite3.
+ */
+export declare function createLocalMemoryProvider(config: LocalMemoryProviderConfig): LocalMemoryProvider;