qlogicagent 2.13.4 → 2.13.5

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

@@ -0,0 +1,486 @@
+/**
+ * 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 { LocalMemoryStore, resolveMemoryDbPath } from "./local-store.js";
+import { resolveMemoryAttachmentsDir } from "./memory-db-path.js";
+import { MemoryAttachmentStore } from "./memory-attachment-store.js";
+import { createEmbeddingProvider } from "./local-embedding.js";
+import { MemoryConsolidator } from "./memory-consolidation.js";
+// Provider
+const PROVIDER_ID = "qmemory-local";
+export class LocalMemoryProvider {
+    providerId = PROVIDER_ID;
+    store;
+    embedding;
+    consolidator;
+    attachmentStore;
+    userIdPrefix;
+    dbPath;
+    constructor(config) {
+        this.dbPath = resolveMemoryDbPath(config.ownerUserId);
+        this.userIdPrefix = config.userIdPrefix ?? "";
+        this.embedding = createEmbeddingProvider(config.embedding);
+        if (!config.createDatabase) {
+            throw new Error("LocalMemoryProvider requires a createDatabase factory. " +
+                "Install better-sqlite3 and pass: (path) => new Database(path)");
+        }
+        const db = config.createDatabase(this.dbPath);
+        this.store = new LocalMemoryStore(db);
+        this.consolidator = new MemoryConsolidator(this.store, (text) => this.buildEmbedding(text));
+        this.attachmentStore = new MemoryAttachmentStore(this.store, resolveMemoryAttachmentsDir(config.ownerUserId));
+    }
+    // Attachments (长期记忆素材) — see MemoryAttachmentStore.
+    /** Persist an uploaded attachment (orphan until linked at commit). */
+    async adoptAttachment(input) {
+        return this.attachmentStore.adopt({ ...input, userId: this.resolveUserId(input.userId) });
+    }
+    /** Resolve an attachment id to its on-disk path (for serving). */
+    async locateAttachment(id) {
+        return this.attachmentStore.locate(id);
+    }
+    /** Drop uploads that were never saved to a memory. */
+    async purgeOrphanAttachments() {
+        return this.attachmentStore.purgeOrphans();
+    }
+    /** Read an attachment's bytes + mime (P2 multimodal understanding). */
+    async readAttachmentBytes(id) {
+        return this.attachmentStore.readBytes(id);
+    }
+    /** Persist the understood/extracted text on an attachment row. */
+    setAttachmentText(id, text) {
+        this.attachmentStore.setExtractedText(id, text);
+    }
+    resolveUserId(userId) {
+        return this.userIdPrefix ? `${this.userIdPrefix}:${userId}` : userId;
+    }
+    async buildEmbedding(text) {
+        if (this.embedding.dimensions === 0)
+            return undefined;
+        try {
+            const embedding = await this.embedding.embed(text);
+            return embedding.length ? embedding : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // MemoryProvider interface
+    async search(query, userId, options) {
+        const resolvedUser = this.resolveUserId(userId);
+        const limit = options?.limit ?? 10;
+        const minScore = options?.minScore ?? 0.1;
+        let queryEmbedding = null;
+        if (this.embedding.dimensions > 0) {
+            try {
+                queryEmbedding = await this.embedding.embed(query);
+            }
+            catch {
+                // Fall back to FTS-only if embedding fails
+            }
+        }
+        // Fetch more than needed for reranking headroom
+        const fetchLimit = Math.min(limit * 3, 50);
+        const hits = this.store.searchHybrid(query, queryEmbedding, resolvedUser, fetchLimit);
+        // Reranker
+        const reranked = this.rerank(hits.map((h) => ({
+            id: h.id,
+            text: h.text,
+            score: h.score,
+            category: h.category,
+            metadata: { ...h.metadata, createdAt: h.metadata?.createdAt, accessCount: h.metadata?.accessCount },
+        })), { preferredCategories: options?.preferredCategories });
+        // Feedback
+        for (const hit of reranked.slice(0, 3)) {
+            this.store.recordAccess(hit.id);
+        }
+        return reranked
+            .filter((h) => h.score >= minScore)
+            .slice(0, limit)
+            .map((h) => ({
+            blockId: h.id,
+            text: h.text,
+            score: h.score,
+            source: PROVIDER_ID,
+            metadata: h.metadata,
+        }));
+    }
+    async ingest(messages, userId, options) {
+        const resolvedUser = this.resolveUserId(userId);
+        const observations = messages
+            .filter((msg) => msg.content?.trim() && msg.content.trim().length >= 10)
+            .map((msg) => ({
+            text: msg.content,
+            category: "conversation",
+            importance: 0.4,
+        }));
+        await this.consolidator.observe(observations, resolvedUser, {
+            source: options?.source ?? "turn",
+            sessionId: options?.sessionId ?? "",
+        });
+    }
+    async addText(text, userId, options) {
+        return this.ingestExtracted([{
+                text,
+                category: options?.category ?? "fact",
+                importance: options?.importance ?? 0.6,
+            }], userId, {
+            ...options,
+            source: options?.source ?? "agent",
+            sessionId: options?.sessionId ?? "",
+        });
+    }
+    async remove(memoryId) {
+        this.store.updateClaimsByMemoryId(memoryId, "archived");
+        await this.attachmentStore.removeByMemoryId(memoryId);
+        return this.store.delete(memoryId);
+    }
+    async update(memoryId, input) {
+        const current = this.store.getById(memoryId);
+        if (!current)
+            return false;
+        const nextText = input.text?.trim();
+        const embedding = nextText && nextText !== current.text
+            ? await this.buildEmbedding(nextText)
+            : undefined;
+        const updated = this.store.update(memoryId, {
+            ...input,
+            text: nextText || undefined,
+            embedding,
+        });
+        if (updated)
+            this.store.updateClaimsByMemoryId(memoryId, "superseded");
+        return updated;
+    }
+    // MemoryProvider interface
+    /**
+     * Commit extracted memory items through the single consolidation pipeline.
+     */
+    async ingestExtracted(items, userId, options) {
+        if (items.length === 0)
+            return emptyConsolidationResult();
+        const resolvedUser = this.resolveUserId(userId);
+        return this.consolidator.commitExtracted(items, resolvedUser, {
+            source: options?.source ?? "agent",
+            sessionId: options?.sessionId ?? "",
+        });
+    }
+    async observeExtracted(items, userId, options) {
+        if (items.length === 0)
+            return emptyConsolidationResult();
+        return this.consolidator.observe(items, this.resolveUserId(userId), {
+            source: options?.source ?? "agent",
+            sessionId: options?.sessionId ?? "",
+        });
+    }
+    async proposeExtracted(items, userId, options) {
+        if (items.length === 0)
+            return emptyConsolidationResult();
+        return this.consolidator.proposeExtracted(items, this.resolveUserId(userId), {
+            source: options?.source ?? "agent",
+            sessionId: options?.sessionId ?? "",
+        });
+    }
+    listClaims(userId) {
+        return this.store.listClaims(this.resolveUserId(userId));
+    }
+    listConflicts(userId) {
+        return this.store.listConflicts(this.resolveUserId(userId));
+    }
+    /**
+     * 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.
+     */
+    async resolveConflicts(userId, opts) {
+        const resolvedUser = this.resolveUserId(userId);
+        const open = this.store.listOpenConflicts(resolvedUser);
+        let conflictsResolved = 0;
+        for (const conflict of open) {
+            const a = this.store.getClaimById(conflict.claimAId);
+            const b = this.store.getClaimById(conflict.claimBId);
+            if (!a || !b) {
+                // Dangling conflict (a claim was deleted) — close it.
+                this.store.setConflictStatus(conflict.id, "resolved");
+                conflictsResolved++;
+                continue;
+            }
+            const winner = pickConflictWinner(a, b);
+            const loser = winner.id === a.id ? b : a;
+            this.store.setClaimStatus(winner.id, "active");
+            this.store.setClaimStatus(loser.id, "superseded");
+            if (loser.memoryId)
+                this.store.archive(loser.memoryId);
+            this.store.setConflictStatus(conflict.id, "resolved");
+            conflictsResolved++;
+        }
+        const claimsPromoted = this.store.promotePendingClaims(resolvedUser, opts?.minEvidenceToPromote ?? 2);
+        return { conflictsResolved, claimsPromoted };
+    }
+    /**
+     * Trigger memory decay - multi-strategy (temporal + staleness + noise).
+     * Also enforces capacity limit and runs vacuum for space reclamation.
+     */
+    async triggerDecay(userId, _maxAgeDays = 90) {
+        const resolvedUser = this.resolveUserId(userId);
+        const result = this.store.runFullDecay(resolvedUser);
+        // Enforce capacity limit (archive excess if over 10k)
+        const capacityArchived = this.store.enforceCapacityLimit(resolvedUser, 10_000);
+        // Purge very old archived records and vacuum if significant work was done
+        if (result.total + capacityArchived > 10) {
+            this.store.exportAndPurgeArchived(resolvedUser, 200); // Discard exported data (cold storage optional)
+            this.store.vacuum();
+        }
+        return { decayed: result.total + capacityArchived };
+    }
+    // Feedback
+    /**
+     * Apply feedback to a memory (useful/irrelevant/outdated/wrong).
+     * Adjusts importance or archives/deletes based on signal.
+     */
+    async feedback(memoryIds, signal) {
+        let affected = 0;
+        for (const id of memoryIds) {
+            if (this.store.applyFeedback(id, signal))
+                affected++;
+        }
+        return { affected };
+    }
+    // User Profile
+    /**
+     * Get a user profile value.
+     */
+    getProfile(userId, key) {
+        return this.store.getProfile(this.resolveUserId(userId), key);
+    }
+    /**
+     * Set a user profile value (upsert).
+     */
+    setProfile(userId, key, value) {
+        this.store.setProfile(this.resolveUserId(userId), key, value);
+    }
+    /**
+     * Get all profile entries for a user.
+     */
+    getAllProfiles(userId) {
+        return this.store.getAllProfiles(this.resolveUserId(userId));
+    }
+    /**
+     * Delete a profile entry.
+     */
+    deleteProfile(userId, key) {
+        return this.store.deleteProfile(this.resolveUserId(userId), key);
+    }
+    // Temporal Synthesis
+    /**
+     * Get memories within a time range, grouped by day.
+     * Powers "what happened last week" type queries.
+     */
+    getTemporalSlice(userId, startMs, endMs, options) {
+        return this.store.getTemporalSlice(this.resolveUserId(userId), startMs, endMs, options);
+    }
+    /**
+     * Get activity summary over recent N days (daily counts + highlights).
+     */
+    getActivitySummary(userId, days = 7) {
+        return this.store.getActivitySummary(this.resolveUserId(userId), days);
+    }
+    /**
+     * 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, options) {
+        return this.store.listByUser(this.resolveUserId(userId), options?.page ?? 1, options?.pageSize ?? 500, options?.activeOnly ?? true);
+    }
+    /**
+     * 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, options) {
+        const result = this.store.getAtlas(this.resolveUserId(userId), options);
+        // Attach lightweight attachment refs to the windowed records (no bytes/extractedText).
+        const ids = (result.records ?? []).map((r) => r.id);
+        if (ids.length > 0) {
+            const refMap = this.attachmentStore.refsForMemories(ids);
+            for (const record of result.records ?? []) {
+                const refs = refMap.get(record.id);
+                if (refs && refs.length > 0)
+                    record.attachments = refs;
+            }
+        }
+        return result;
+    }
+    findByEventDate(userId, targetDate, toleranceDays = 1) {
+        return this.store.findByEventDate(this.resolveUserId(userId), targetDate, toleranceDays);
+    }
+    /**
+     * 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.
+     */
+    async findRelatedEvents(text, userId, options) {
+        const resolvedUser = this.resolveUserId(userId);
+        const minSim = options?.minSimilarity ?? 0.55;
+        const maxSim = options?.maxSimilarity ?? 0.82; // Above 0.82 = dedup territory
+        const maxDaysBack = options?.maxDaysBack ?? 14;
+        const limit = options?.limit ?? 5;
+        // Need embedding for similarity comparison
+        if (this.embedding.dimensions === 0)
+            return [];
+        let queryEmbedding;
+        try {
+            queryEmbedding = await this.embedding.embed(text);
+        }
+        catch {
+            return [];
+        }
+        const vectorHits = this.store.searchVector(queryEmbedding, resolvedUser, limit * 3, minSim);
+        const cutoff = Date.now() - maxDaysBack * 86_400_000;
+        return vectorHits
+            .filter(h => {
+            const sim = h.metadata?.cosineSimilarity ?? h.score;
+            const createdAt = h.metadata?.createdAt ?? 0;
+            return sim >= minSim && sim < maxSim && createdAt >= cutoff;
+        })
+            .slice(0, limit)
+            .map(h => ({
+            id: h.id,
+            text: h.text,
+            score: h.metadata?.cosineSimilarity ?? h.score,
+            date: new Date(h.metadata?.createdAt ?? Date.now()).toISOString().slice(0, 10),
+        }));
+    }
+    /**
+     * Synthesize a temporal narrative from memories in a time range.
+     * Returns a structured timeline suitable for prompt injection.
+     */
+    synthesizeTimeline(userId, startMs, endMs) {
+        const slices = this.getTemporalSlice(userId, startMs, endMs);
+        if (slices.length === 0)
+            return "No memories in this time range.";
+        const lines = [];
+        for (const slice of slices) {
+            lines.push(`## ${slice.date}`);
+            for (const mem of slice.memories) {
+                const prefix = mem.importance >= 0.7 ? "*" : "-";
+                lines.push(`${prefix} [${mem.category}] ${mem.text}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    // Reranker
+    /**
+     * 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, options) {
+        const recencyWindow = (options?.recencyBoostDays ?? 7) * 86_400_000;
+        const now = Date.now();
+        const preferred = new Set(options?.preferredCategories ?? []);
+        return results
+            .map((r) => {
+            let boostedScore = r.score;
+            // Recency boost: memories created within recencyWindow get +0.1 max
+            const createdAt = r.metadata?.createdAt ?? 0;
+            if (createdAt > 0) {
+                const age = now - createdAt;
+                if (age < recencyWindow) {
+                    boostedScore += 0.1 * (1 - age / recencyWindow);
+                }
+            }
+            // Access frequency boost: frequently accessed memories are more relevant
+            const accessCount = r.metadata?.accessCount ?? 0;
+            if (accessCount > 0) {
+                boostedScore += Math.min(0.05, accessCount * 0.01);
+            }
+            // Category alignment boost
+            if (preferred.size > 0 && r.category && preferred.has(r.category)) {
+                boostedScore += 0.08;
+            }
+            return { ...r, score: Math.min(1.0, boostedScore) };
+        })
+            .sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Health check - always healthy for local store.
+     */
+    async health() {
+        return {
+            status: "healthy",
+            memoryCount: 0,
+            dbPath: this.dbPath,
+        };
+    }
+    /**
+     * Get memory count for a user.
+     */
+    count(userId) {
+        return this.store.count(this.resolveUserId(userId));
+    }
+    /**
+     * Reset all memories for a user.
+     */
+    async resetUser(userId) {
+        return this.store.resetUser(this.resolveUserId(userId));
+    }
+    /**
+     * Close the database connection.
+     */
+    close() {
+        this.store.close();
+    }
+}
+// Factory
+/**
+ * Create a local memory provider (convenience factory).
+ * Caller must provide the createDatabase factory to avoid hard dependency on better-sqlite3.
+ */
+export function createLocalMemoryProvider(config) {
+    return new LocalMemoryProvider(config);
+}
+function emptyConsolidationResult() {
+    return {
+        observationsAdded: 0,
+        proposalsAdded: 0,
+        claimsAdded: 0,
+        conflictsAdded: 0,
+        memoriesAdded: 0,
+        observationIds: [],
+        proposalIds: [],
+        claimIds: [],
+        conflictIds: [],
+    };
+}
+/**
+ * Pick the surviving claim in a conflict: higher source priority wins, then
+ * higher confidence, then more recent. Deterministic and total.
+ */
+function pickConflictWinner(a, b) {
+    if (a.sourcePriority !== b.sourcePriority)
+        return a.sourcePriority > b.sourcePriority ? a : b;
+    if (a.confidence !== b.confidence)
+        return a.confidence > b.confidence ? a : b;
+    return a.updatedAt >= b.updatedAt ? a : b;
+}

package/dist/skills/memory/local-store-records.d.ts

@@ -0,0 +1,184 @@
+export interface MemoryRecord {
+    id: string;
+    text: string;
+    userId: string;
+    category: string;
+    importance: number;
+    confidence: number;
+    source: string;
+    sessionId: string;
+    eventDate: string;
+    tags: string[];
+    embedding: Float32Array | null;
+    createdAt: number;
+    updatedAt: number;
+    accessCount: number;
+    lastAccessedAt: number;
+    isArchived: boolean;
+}
+export interface MemoryInsertInput {
+    text: string;
+    userId: string;
+    category?: string;
+    importance?: number;
+    confidence?: number;
+    source?: string;
+    sessionId?: string;
+    eventDate?: string;
+    tags?: string[];
+    embedding?: Float32Array;
+}
+export interface MemoryUpdateInput {
+    text?: string;
+    category?: string;
+    importance?: number;
+    source?: string;
+    eventDate?: string;
+    tags?: string[];
+    embedding?: Float32Array | null;
+}
+export interface MemorySearchHit {
+    id: string;
+    text: string;
+    score: number;
+    category: string;
+    importance: number;
+    metadata: Record<string, unknown>;
+}
+export interface MemoryAtlasBucket {
+    id: string;
+    startAt: number;
+    endAt: number;
+    count: number;
+    avgImportance: number;
+    avgConfidence: number;
+    topCategory: string;
+}
+export interface MemoryAtlasCluster {
+    id: string;
+    label: string;
+    kind: "source" | "category" | "tag";
+    count: number;
+    startAt: number;
+    endAt: number;
+    avgImportance: number;
+    avgConfidence: number;
+    topCategory: string;
+}
+export interface MemoryAtlasWindowCursor {
+    startAt: number;
+    endAt: number;
+    centerAt: number;
+    pageSize: number;
+    hasBefore: boolean;
+    hasAfter: boolean;
+}
+export interface MemoryAtlasResult {
+    totalCount: number;
+    records: MemoryRecord[];
+    buckets: MemoryAtlasBucket[];
+    clusters: MemoryAtlasCluster[];
+    windowCursor: MemoryAtlasWindowCursor | null;
+    timeRange: {
+        startAt: number;
+        endAt: number;
+    } | null;
+}
+export type MemorySourceKind = "manual" | "explicit" | "document" | "image" | "video" | "auto" | "turn" | "dream" | "agent";
+export type MemoryClaimStatus = "active" | "superseded" | "conflicted" | "archived" | "pending_confirmation";
+export type MemoryProposalStatus = "pending" | "accepted" | "merged" | "conflicted" | "rejected";
+export interface MemoryObservationInput {
+    userId: string;
+    text: string;
+    source: string;
+    sourcePriority: number;
+    sessionId?: string;
+    evidenceType?: string;
+    payload?: Record<string, unknown>;
+}
+export interface MemoryObservationRecord extends Required<Omit<MemoryObservationInput, "payload" | "sessionId" | "evidenceType">> {
+    id: string;
+    sessionId: string;
+    evidenceType: string;
+    payload: Record<string, unknown>;
+    createdAt: number;
+}
+export interface MemoryProposalInput {
+    userId: string;
+    observationIds: string[];
+    text: string;
+    category: string;
+    importance: number;
+    confidence: number;
+    source: string;
+    sourcePriority: number;
+    entity: string;
+    predicate: string;
+    value: Record<string, unknown>;
+    validTime?: string;
+    tags?: string[];
+    status?: MemoryProposalStatus;
+    relatedClaimIds?: string[];
+}
+export interface MemoryProposalRecord extends Omit<MemoryProposalInput, "value" | "validTime" | "tags" | "status" | "relatedClaimIds"> {
+    id: string;
+    value: Record<string, unknown>;
+    validTime: string;
+    tags: string[];
+    status: MemoryProposalStatus;
+    relatedClaimIds: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MemoryClaimInput {
+    userId: string;
+    memoryId?: string;
+    entity: string;
+    predicate: string;
+    value: Record<string, unknown>;
+    text: string;
+    category: string;
+    importance: number;
+    confidence: number;
+    source: string;
+    sourcePriority: number;
+    status: MemoryClaimStatus;
+    validTime?: string;
+    evidenceIds: string[];
+    supersedesClaimId?: string;
+    conflictGroupId?: string;
+}
+export interface MemoryClaimRecord extends Omit<MemoryClaimInput, "memoryId" | "value" | "validTime" | "supersedesClaimId" | "conflictGroupId"> {
+    id: string;
+    memoryId: string;
+    value: Record<string, unknown>;
+    validTime: string;
+    supersedesClaimId: string;
+    conflictGroupId: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MemoryConflictRecord {
+    id: string;
+    userId: string;
+    claimAId: string;
+    claimBId: string;
+    reason: string;
+    status: "open" | "resolved" | "dismissed";
+    createdAt: number;
+    updatedAt: number;
+}
+export interface SqliteDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    pragma(pragma: string): unknown;
+    close(): void;
+}
+export interface SqliteStatement {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}

package/dist/skills/memory/local-store-records.js

@@ -0,0 +1 @@
+export {};