qlogicagent 0.2.1 → 0.3.0

package/dist/skills/memory-extractor.js

@@ -1,173 +0,0 @@
-// ============================================================
-// Memory Extractor — LLM-based fact extraction from conversation.
-//
-// Runs server-side via an OpenAI-compatible LLM endpoint (e.g.
-// admin/new-api). Ports qmemory's extraction prompt into a
-// reusable TypeScript module so extraction happens where the
-// LLM key lives, NOT on the local qmemory instance.
-// ============================================================
-// ── Extraction Tool Schema (matches qmemory extractor) ──────
-const EXTRACTION_TOOL = {
-    type: "function",
-    function: {
-        name: "save_extraction",
-        description: "Save all extracted memories and profile updates from the conversation.",
-        parameters: {
-            type: "object",
-            properties: {
-                memories: {
-                    type: "array",
-                    description: "Atomic facts extracted from both user and assistant. One per distinct fact.",
-                    items: {
-                        type: "object",
-                        properties: {
-                            text: { type: "string", description: "Self-contained fact (one sentence, no pronouns)" },
-                            category: { type: "string", enum: ["fact", "preference", "event", "plan", "opinion", "advice", "discussion"] },
-                            importance: { type: "number", description: "0-1 scale. Named entities>=0.5, facts with numbers>=0.4, preferences>=0.6, identity>=0.8" },
-                            speaker: { type: "string", enum: ["user", "assistant", "both"] },
-                            event_date: { type: "string", description: "ISO YYYY-MM-DD or null" },
-                            tags: { type: "array", items: { type: "string" }, maxItems: 3 },
-                        },
-                        required: ["text", "category", "importance", "speaker"],
-                    },
-                },
-                profile_updates: {
-                    type: "array",
-                    description: "User traits/preferences to track.",
-                    items: {
-                        type: "object",
-                        properties: {
-                            category: { type: "string", enum: ["preference", "fact", "habit", "style"] },
-                            key: { type: "string", description: "Short ID (e.g. job, location)" },
-                            value: { type: "string" },
-                            confidence: { type: "number" },
-                        },
-                        required: ["category", "key", "value"],
-                    },
-                },
-            },
-            required: ["memories"],
-        },
-    },
-};
-// ── System Prompt (ported from qmemory extractor.py) ────────
-function buildSystemPrompt(today, isChinese) {
-    const base = `You are a memory extraction engine. Today's date: ${today}.
-
-Extract from the conversation below by calling the save_extraction tool with ALL results at once.
-
-Rules:
-- **LANGUAGE**: Write in the SAME language as the conversation. NEVER translate.
-- Extract ALL meaningful facts from BOTH [User] and [Assistant] lines. Skip greetings/filler.
-- **BE THOROUGH**: Extract EVERY named person+role, activity+details, financial/numeric detail, temporal event, relationship, item owned, change over time, and assistant's recommendations.
-- **ANTI-SUMMARIZATION**: Keep exact numbers, locations, dates, names, metrics.
-- For event_date: convert relative dates using today (${today}).
-- Set speaker="assistant" for assistant-originated facts.
-- **IMPORTANCE SCORING**:
-  0.9-1.0: Core identity (name, DOB, nationality)
-  0.7-0.9: Key relationships, major life events, career facts
-  0.5-0.7: Specific facts with names/numbers/dates, preferences, hobbies
-  0.3-0.5: Casual mentions, assistant recommendations, general opinions
-  NEVER assign importance < 0.2 to any memory containing proper nouns, numbers, dates, or specific entities.`;
-    if (isChinese) {
-        return base + `\n- Extract EVERY number/price/measurement as separate memories with exact figures.\n- Minimum density: ~2-3 memories per 200 tokens of conversation.`;
-    }
-    return base;
-}
-function isChinese(text) {
-    let cn = 0;
-    for (const c of text) {
-        if (c >= "\u4e00" && c <= "\u9fff")
-            cn++;
-    }
-    return cn / (text.length || 1) > 0.15;
-}
-// ── Parser ──────────────────────────────────────────────────
-function parseToolCallResult(argsJson) {
-    let parsed;
-    try {
-        parsed = JSON.parse(argsJson);
-    }
-    catch {
-        return { memories: [], profileUpdates: [] };
-    }
-    const rawMemories = Array.isArray(parsed.memories) ? parsed.memories : [];
-    const rawProfiles = Array.isArray(parsed.profile_updates) ? parsed.profile_updates : [];
-    const memories = rawMemories
-        .filter((m) => !!m && typeof m === "object")
-        .filter((m) => typeof m.text === "string" && m.text.trim())
-        .map((m) => ({
-        text: String(m.text).trim(),
-        category: typeof m.category === "string" ? m.category : "fact",
-        importance: typeof m.importance === "number" ? Math.max(0, Math.min(1, m.importance)) : 0.5,
-        speaker: typeof m.speaker === "string" ? m.speaker : "user",
-        ...(typeof m.event_date === "string" && m.event_date ? { event_date: m.event_date } : {}),
-        ...(Array.isArray(m.tags) ? { tags: m.tags.filter((t) => typeof t === "string") } : {}),
-    }));
-    const profileUpdates = rawProfiles
-        .filter((p) => !!p && typeof p === "object")
-        .filter((p) => typeof p.key === "string" && typeof p.value === "string")
-        .map((p) => ({
-        category: typeof p.category === "string" ? p.category : "fact",
-        key: String(p.key).trim(),
-        value: String(p.value).trim(),
-        confidence: typeof p.confidence === "number" ? Math.max(0, Math.min(1, p.confidence)) : 0.5,
-    }));
-    return { memories, profileUpdates };
-}
-// ── Factory ─────────────────────────────────────────────────
-const DEFAULT_MODEL = "deepseek-chat";
-const MIN_TEXT_LENGTH = 20;
-/**
- * Create a memory extractor backed by an OpenAI-compatible LLM endpoint.
- *
- * The `complete` function is injected by the consumer so that
- * skills layer stays transport-agnostic (no admin/new-api dependency).
- */
-export function createMemoryExtractor(complete, options) {
-    const model = options?.model ?? DEFAULT_MODEL;
-    return {
-        /**
-         * Extract structured memories from a conversation fragment.
-         * Returns empty result if text is too short or LLM call fails.
-         */
-        async extract(conversationText) {
-            const trimmed = conversationText.trim();
-            if (trimmed.length < MIN_TEXT_LENGTH) {
-                return { memories: [], profileUpdates: [] };
-            }
-            const today = new Date().toISOString().slice(0, 10);
-            const systemPrompt = buildSystemPrompt(today, isChinese(trimmed));
-            try {
-                const response = await complete({
-                    model,
-                    messages: [
-                        { role: "system", content: systemPrompt },
-                        { role: "user", content: `Conversation:\n${trimmed}` },
-                    ],
-                    tools: [EXTRACTION_TOOL],
-                    tool_choice: { type: "function", function: { name: "save_extraction" } },
-                    temperature: 0.1,
-                    max_tokens: 4000,
-                });
-                const toolCalls = response.choices?.[0]?.message?.tool_calls;
-                if (!toolCalls?.length) {
-                    return { memories: [], profileUpdates: [] };
-                }
-                // Merge results from all tool calls (usually just one)
-                const merged = { memories: [], profileUpdates: [] };
-                for (const tc of toolCalls) {
-                    if (tc.function?.name === "save_extraction" && tc.function.arguments) {
-                        const partial = parseToolCallResult(tc.function.arguments);
-                        merged.memories.push(...partial.memories);
-                        merged.profileUpdates.push(...partial.profileUpdates);
-                    }
-                }
-                return merged;
-            }
-            catch {
-                return { memories: [], profileUpdates: [] };
-            }
-        },
-    };
-}

package/dist/skills/memory-query-tool.js

@@ -1,127 +0,0 @@
-// ============================================================
-// Memory Query Tool — explicit agent-initiated memory recall.
-//
-// Allows the LLM to actively query recalled memories and user
-// profile when it determines that the current context is
-// insufficient for a good response.
-// ============================================================
-export const MEMORY_QUERY_TOOL_NAME = "memory_query";
-// ── Schema ──────────────────────────────────────────────────
-export const MEMORY_QUERY_TOOL_SCHEMA = {
-    type: "object",
-    properties: {
-        query: {
-            type: "string",
-            description: [
-                "The memory query — a natural language description of what you want to recall.",
-                "Examples:",
-                "• '用户的编程语言偏好' → searches tech preferences",
-                "• '用户之前提到的项目' → searches project history",
-                "• '上次画图的风格' → searches media generation history",
-                "• 'user's name and location' → searches personal facts",
-                "Be specific: '用户喜欢什么图片风格' is better than '用户偏好'.",
-            ].join("\n"),
-        },
-        category: {
-            type: "string",
-            description: [
-                "Optional: narrow the search to a specific category.",
-                "• 'profile' — user preferences, expertise, communication style",
-                "• 'facts' — recalled long-term memories",
-                "• 'media' — media generation preferences (image style, music genre, etc.)",
-                "• 'projects' — project context and tech stack",
-                "If omitted, searches across all categories.",
-            ].join("\n"),
-        },
-    },
-    required: ["query"],
-};
-// ── Tool factory ────────────────────────────────────────────
-export function createMemoryQueryTool(deps) {
-    return {
-        name: MEMORY_QUERY_TOOL_NAME,
-        label: "Memory Query",
-        description: [
-            "Query your memory about this user to recall facts, preferences, or history.",
-            "Use this when you need information that might have been shared in previous conversations.",
-            "",
-            "Call this tool when:",
-            "- You want to personalize a response based on user preferences",
-            "- You recall the user mentioned something relevant but it's not in the current context",
-            "- You need to check media preferences before generating images/music/video",
-            "- You want to reference the user's project context or tech stack",
-            "",
-            "This tool searches recalled memories and the user profile.",
-            "It does NOT search the current conversation — that's already in your context.",
-            "Results may be empty if no relevant memories exist.",
-        ].join("\n"),
-        parameters: MEMORY_QUERY_TOOL_SCHEMA,
-        execute: async (_toolCallId, params) => {
-            const query = params.query?.trim();
-            if (!query) {
-                return {
-                    content: [{ type: "text", text: "query parameter is required." }],
-                    details: { type: "memory_query", found: false, errorCode: "empty_query" },
-                };
-            }
-            const category = params.category?.trim() || undefined;
-            const userId = deps?.userId ?? "user";
-            const sections = [];
-            // 1. Memory recall search
-            if (!category || category === "facts" || category === "projects") {
-                try {
-                    const facts = deps?.queryGraph?.(query, userId) ?? [];
-                    if (facts.length > 0) {
-                        sections.push("## Recalled Memories\n" + facts.map((f) => `• ${f}`).join("\n"));
-                    }
-                }
-                catch { /* degrade gracefully */ }
-            }
-            // 2. User Profile summary
-            if (!category || category === "profile" || category === "projects") {
-                try {
-                    const profileText = deps?.getProfileSummary?.(userId) ?? null;
-                    if (profileText) {
-                        sections.push("## User Profile\n" + profileText);
-                    }
-                }
-                catch { /* degrade gracefully */ }
-            }
-            // 3. Media Preferences
-            if (!category || category === "media") {
-                try {
-                    const mediaPrefs = deps?.getMediaPreferences?.(userId) ?? null;
-                    if (mediaPrefs) {
-                        const lines = [];
-                        if (mediaPrefs.imageStyle)
-                            lines.push(`• Image style: ${mediaPrefs.imageStyle}`);
-                        if (mediaPrefs.videoStyle)
-                            lines.push(`• Video style: ${mediaPrefs.videoStyle}`);
-                        if (mediaPrefs.musicGenre)
-                            lines.push(`• Music genre: ${mediaPrefs.musicGenre}`);
-                        if (mediaPrefs.musicMood)
-                            lines.push(`• Music mood: ${mediaPrefs.musicMood}`);
-                        if (mediaPrefs.primaryPurpose)
-                            lines.push(`• Primary purpose: ${mediaPrefs.primaryPurpose}`);
-                        if (mediaPrefs.colorPreference)
-                            lines.push(`• Color preference: ${mediaPrefs.colorPreference}`);
-                        if (lines.length > 0) {
-                            sections.push("## Media Preferences\n" + lines.join("\n"));
-                        }
-                    }
-                }
-                catch { /* degrade gracefully */ }
-            }
-            if (sections.length === 0) {
-                return {
-                    content: [{ type: "text", text: "No relevant memories found for this query. The user may not have shared this information yet." }],
-                    details: { type: "memory_query", found: false, query },
-                };
-            }
-            return {
-                content: [{ type: "text", text: sections.join("\n\n") }],
-                details: { type: "memory_query", found: true, query, category: category ?? "all", sectionCount: sections.length },
-            };
-        },
-    };
-}

package/dist/skills/memory-store.js

@@ -1,228 +0,0 @@
-// ============================================================
-// Memory Store — character-bounded local memory for agent notes.
-//
-// Inspired by Hermes' MemoryStore design:
-// - Two targets: "memory" (agent notes) + "user" (user profile)
-// - § delimiter between entries
-// - Frozen snapshot for system prompt (KV cache stability)
-// - Exact duplicate rejection
-// - Content safety scanning
-// - Pure in-memory; persistence is the consumer's responsibility.
-// ============================================================
-import { isMemoryContentSafe } from "./memory-tool.js";
-// ── Constants ───────────────────────────────────────────────
-export const MEMORY_ENTRY_DELIMITER = "\n§\n";
-export const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
-export const DEFAULT_USER_CHAR_LIMIT = 1375;
-// ── MemoryStore class ───────────────────────────────────────
-export class MemoryStore {
-    memoryEntries = [];
-    userEntries = [];
-    frozenSnapshot = { memory: "", user: "" };
-    snapshotFrozen = false;
-    memoryCharLimit;
-    userCharLimit;
-    constructor(options) {
-        this.memoryCharLimit = options?.memoryCharLimit ?? DEFAULT_MEMORY_CHAR_LIMIT;
-        this.userCharLimit = options?.userCharLimit ?? DEFAULT_USER_CHAR_LIMIT;
-    }
-    // ── Load / Serialize ────────────────────────────────────
-    /**
-     * Load from serialized form (e.g. from PG or filesystem).
-     * Deduplicates entries on load.
-     */
-    loadFromSerialized(data) {
-        this.memoryEntries = deduplicateEntries(parseEntries(data.memory ?? ""));
-        this.userEntries = deduplicateEntries(parseEntries(data.user ?? ""));
-    }
-    /**
-     * Serialize current live state for persistence.
-     */
-    serialize() {
-        return {
-            memory: this.memoryEntries.join(MEMORY_ENTRY_DELIMITER),
-            user: this.userEntries.join(MEMORY_ENTRY_DELIMITER),
-        };
-    }
-    // ── Snapshot (frozen for system prompt) ─────────────────
-    /**
-     * Freeze current entries for system prompt injection.
-     * Call once at session start. After freezing, mutations update
-     * live state but NOT the system prompt block.
-     */
-    freezeSnapshot() {
-        this.frozenSnapshot = {
-            memory: this.renderBlock("memory", this.memoryEntries),
-            user: this.renderBlock("user", this.userEntries),
-        };
-        this.snapshotFrozen = true;
-    }
-    /**
-     * Get frozen system prompt block for the given target.
-     * Returns empty string if no entries or not yet frozen.
-     */
-    getSystemPromptBlock(target) {
-        if (!this.snapshotFrozen) {
-            // Auto-freeze on first access
-            this.freezeSnapshot();
-        }
-        return this.frozenSnapshot[target];
-    }
-    // ── Mutations ───────────────────────────────────────────
-    add(target, content) {
-        const trimmed = content.trim();
-        if (!trimmed) {
-            return this.errorResult(target, "Content cannot be empty.", "empty_content");
-        }
-        if (!isMemoryContentSafe(trimmed)) {
-            return this.errorResult(target, "Content rejected: potential injection detected.", "unsafe_content");
-        }
-        const entries = this.entriesFor(target);
-        // Exact duplicate check
-        if (entries.includes(trimmed)) {
-            return this.successResult(target, "Entry already exists (no change).");
-        }
-        // Character budget check
-        const newEntries = [...entries, trimmed];
-        const newTotal = newEntries.join(MEMORY_ENTRY_DELIMITER).length;
-        if (newTotal > this.charLimitFor(target)) {
-            const usage = this.formatUsage(target);
-            return this.errorResult(target, `Memory full (${usage}). Remove old entries first.`, "over_limit");
-        }
-        entries.push(trimmed);
-        return this.successResult(target, "Entry added.");
-    }
-    replace(target, oldText, newContent) {
-        const searchText = oldText.trim();
-        const replacement = newContent.trim();
-        if (!searchText) {
-            return this.errorResult(target, "old_text cannot be empty.", "empty_old_text");
-        }
-        if (!replacement) {
-            return this.errorResult(target, "content cannot be empty.", "empty_content");
-        }
-        if (!isMemoryContentSafe(replacement)) {
-            return this.errorResult(target, "Content rejected: potential injection detected.", "unsafe_content");
-        }
-        const entries = this.entriesFor(target);
-        const matchIndices = entries
-            .map((entry, i) => entry.includes(searchText) ? i : -1)
-            .filter((i) => i >= 0);
-        if (matchIndices.length === 0) {
-            return this.errorResult(target, `No entry contains: "${clipForMessage(searchText)}"`, "not_found");
-        }
-        if (matchIndices.length > 1) {
-            // Check if all matches are identical (harmless duplicate)
-            const unique = new Set(matchIndices.map((i) => entries[i]));
-            if (unique.size > 1) {
-                return this.errorResult(target, `Multiple entries match: "${clipForMessage(searchText)}" (${matchIndices.length} matches). Be more specific.`, "ambiguous_match");
-            }
-        }
-        // Replace first match
-        const matchIndex = matchIndices[0];
-        // Check char limit with replacement
-        const projected = [...entries];
-        projected[matchIndex] = replacement;
-        const projectedTotal = projected.join(MEMORY_ENTRY_DELIMITER).length;
-        if (projectedTotal > this.charLimitFor(target)) {
-            const usage = this.formatUsage(target);
-            return this.errorResult(target, `Replacement would exceed limit (${usage}).`, "over_limit");
-        }
-        entries[matchIndex] = replacement;
-        return this.successResult(target, "Entry replaced.");
-    }
-    remove(target, oldText) {
-        const searchText = oldText.trim();
-        if (!searchText) {
-            return this.errorResult(target, "old_text cannot be empty.", "empty_old_text");
-        }
-        const entries = this.entriesFor(target);
-        const matchIndices = entries
-            .map((entry, i) => entry.includes(searchText) ? i : -1)
-            .filter((i) => i >= 0);
-        if (matchIndices.length === 0) {
-            return this.errorResult(target, `No entry contains: "${clipForMessage(searchText)}"`, "not_found");
-        }
-        // Remove all matches (safe: if they all contain the substring, remove them all)
-        for (let i = matchIndices.length - 1; i >= 0; i--) {
-            entries.splice(matchIndices[i], 1);
-        }
-        return this.successResult(target, matchIndices.length === 1 ? "Entry removed." : `${matchIndices.length} entries removed.`);
-    }
-    // ── Read-only accessors ─────────────────────────────────
-    getEntries(target) {
-        return this.entriesFor(target);
-    }
-    getUsage(target) {
-        const entries = this.entriesFor(target);
-        const used = entries.length > 0 ? entries.join(MEMORY_ENTRY_DELIMITER).length : 0;
-        const limit = this.charLimitFor(target);
-        return { used, limit, percent: limit > 0 ? Math.round((used / limit) * 100) : 0 };
-    }
-    isEmpty() {
-        return this.memoryEntries.length === 0 && this.userEntries.length === 0;
-    }
-    // ── Private helpers ─────────────────────────────────────
-    entriesFor(target) {
-        return target === "user" ? this.userEntries : this.memoryEntries;
-    }
-    charLimitFor(target) {
-        return target === "user" ? this.userCharLimit : this.memoryCharLimit;
-    }
-    formatUsage(target) {
-        const { used, limit, percent } = this.getUsage(target);
-        return `${percent}% — ${used}/${limit} chars`;
-    }
-    renderBlock(target, entries) {
-        if (entries.length === 0)
-            return "";
-        const label = target === "user" ? "USER PROFILE" : "MEMORY";
-        const usage = this.formatUsage(target);
-        const divider = "══════════════════════════════════════════════════════════";
-        const body = entries.join(MEMORY_ENTRY_DELIMITER);
-        return `${divider}\n${label} (your personal notes) [${usage}]\n${divider}\n${body}`;
-    }
-    successResult(target, message) {
-        const entries = this.entriesFor(target);
-        return {
-            ok: true,
-            message,
-            target,
-            entries,
-            entryCount: entries.length,
-            usage: this.formatUsage(target),
-        };
-    }
-    errorResult(target, message, errorCode) {
-        const entries = this.entriesFor(target);
-        return {
-            ok: false,
-            message,
-            target,
-            entries,
-            entryCount: entries.length,
-            usage: this.formatUsage(target),
-            errorCode,
-        };
-    }
-}
-// ── Utilities ─────────────────────────────────────────────
-function parseEntries(raw) {
-    if (!raw.trim())
-        return [];
-    return raw.split(MEMORY_ENTRY_DELIMITER).map((e) => e.trim()).filter(Boolean);
-}
-function deduplicateEntries(entries) {
-    const seen = new Set();
-    return entries.filter((entry) => {
-        if (seen.has(entry))
-            return false;
-        seen.add(entry);
-        return true;
-    });
-}
-function clipForMessage(text, maxLength = 60) {
-    if (text.length <= maxLength)
-        return text;
-    return `${text.slice(0, maxLength - 1).trimEnd()}…`;
-}