qlogicagent 2.13.5 → 2.13.7

package/dist/runtime/memory/find-relevant-memories.js

@@ -1,270 +0,0 @@
-// ============================================================
-// P4: Cross-file semantic memory recall (CC findRelevantMemories parity).
-//
-// Scans MEMDIR topic files and selects the most relevant ones for
-// the current user query. Content is injected alongside QMemory
-// results during memory.before_recall.
-//
-// Strategy: keyword + filename heuristics (no LLM sideQuery needed
-// because our topic files are small and well-named). Falls back to
-// QMemory vector search for borderline scoring when available.
-//
-// CC reference: src/memdir/findRelevantMemories.ts
-//              src/memdir/memoryScan.ts
-// ============================================================
-import { readFile, readdir, stat } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-// ── Configuration ───────────────────────────────────────────
-export const RELEVANT_MEMORIES_CONFIG = {
-    /** Max topic files to consider during scan. */
-    MAX_SCAN_FILES: 100,
-    /** Max files to surface per turn. */
-    MAX_SELECTED: 5,
-    /** Max bytes per surfaced file (CC: 4096). */
-    MAX_FILE_BYTES: 4096,
-    /** Max total bytes for all surfaced files combined. */
-    MAX_TOTAL_BYTES: 20 * 1024,
-    /** Minimum score to be selected (0.0-1.0). */
-    MIN_SCORE: 0.20,
-    /** Lines to read for header/description extraction. */
-    HEADER_LINES: 10,
-    /** Recency boost: files modified within this many days get a bonus. */
-    RECENCY_DAYS: 7,
-    /** Recency boost amount. */
-    RECENCY_BOOST: 0.15,
-};
-// ── Main Entry Point ────────────────────────────────────────
-/**
- * Find memory files relevant to a user query.
- *
- * CC parity: scans topic files, scores by keyword + filename + recency,
- * selects top-N, loads content. No LLM needed (unlike CC's Sonnet call).
- *
- * @param query - User query text
- * @param memoryDir - Root of the MEMDIR directory (~/.qlogicagent/memory/)
- * @param alreadySurfaced - Paths already shown in prior turns (for dedup)
- * @returns Relevant memories with content, sorted by score
- */
-export async function findRelevantMemories(query, memoryDir, alreadySurfaced = new Set()) {
-    if (!query.trim() || !existsSync(memoryDir))
-        return [];
-    // Single-word queries lack context for meaningful matching
-    const words = query.trim().split(/\s+/);
-    if (words.length < 2 && words[0].length < 4)
-        return [];
-    // Step 1: Scan headers
-    const headers = await scanMemoryHeaders(memoryDir);
-    if (headers.length === 0)
-        return [];
-    // Step 2: Filter already-surfaced
-    const candidates = headers.filter(h => !alreadySurfaced.has(h.filePath));
-    if (candidates.length === 0)
-        return [];
-    // Step 3: Score relevance
-    const scored = scoreRelevance(query, candidates);
-    // Step 4: Select top-N above threshold
-    const selected = scored
-        .filter(s => s.score >= RELEVANT_MEMORIES_CONFIG.MIN_SCORE)
-        .slice(0, RELEVANT_MEMORIES_CONFIG.MAX_SELECTED);
-    if (selected.length === 0)
-        return [];
-    // Step 5: Load content (with truncation + total budget)
-    return loadSelectedContent(selected);
-}
-// ── Scan ────────────────────────────────────────────────────
-/**
- * Scan memory directory for topic files (excludes INDEX.md).
- * Returns headers sorted by modification time (newest first).
- */
-export async function scanMemoryHeaders(memoryDir) {
-    if (!existsSync(memoryDir))
-        return [];
-    let entries;
-    try {
-        entries = await readdir(memoryDir);
-    }
-    catch {
-        return [];
-    }
-    const mdFiles = entries.filter(f => f.endsWith(".md") && f !== "INDEX.md");
-    const results = await Promise.allSettled(mdFiles.map(async (filename) => {
-        const filePath = join(memoryDir, filename);
-        const st = await stat(filePath);
-        const content = await readFile(filePath, "utf-8");
-        // Extract description from first non-heading, non-empty line
-        const lines = content.split("\n");
-        let description = null;
-        for (let i = 0; i < Math.min(lines.length, RELEVANT_MEMORIES_CONFIG.HEADER_LINES); i++) {
-            const line = lines[i].trim();
-            if (!line || line.startsWith("#") || line.startsWith("---"))
-                continue;
-            description = line.slice(0, 150);
-            break;
-        }
-        // Infer category from filename prefix
-        const category = inferCategory(filename);
-        return {
-            filename,
-            filePath,
-            mtimeMs: st.mtimeMs,
-            sizeBytes: st.size,
-            description,
-            category,
-        };
-    }));
-    return results
-        .filter((r) => r.status === "fulfilled")
-        .map(r => r.value)
-        .sort((a, b) => b.mtimeMs - a.mtimeMs)
-        .slice(0, RELEVANT_MEMORIES_CONFIG.MAX_SCAN_FILES);
-}
-/**
- * Score each candidate's relevance to the query.
- *
- * Scoring factors:
- * 1. Filename keyword overlap (strongest signal)
- * 2. Description keyword overlap
- * 3. Category alignment with query domain
- * 4. Recency boost (recent files get priority)
- */
-function scoreRelevance(query, candidates) {
-    const queryWords = tokenize(query);
-    if (queryWords.length === 0)
-        return [];
-    const now = Date.now();
-    const recencyWindow = RELEVANT_MEMORIES_CONFIG.RECENCY_DAYS * 24 * 60 * 60 * 1000;
-    const scored = candidates.map(header => {
-        let score = 0;
-        // Factor 1: Filename keyword match (0 - 0.5)
-        const filenameTokens = tokenize(header.filename.replace(/\.md$/, "").replace(/[-_]/g, " "));
-        const filenameOverlap = queryWords.filter(w => filenameTokens.some(ft => ft.includes(w) || w.includes(ft))).length;
-        score += Math.min(0.5, (filenameOverlap / queryWords.length) * 0.5);
-        // Factor 2: Description keyword match (0 - 0.3)
-        if (header.description) {
-            const descTokens = tokenize(header.description);
-            const descOverlap = queryWords.filter(w => descTokens.some(dt => dt.includes(w) || w.includes(dt))).length;
-            score += Math.min(0.3, (descOverlap / queryWords.length) * 0.3);
-        }
-        // Factor 3: Category alignment (0 - 0.1)
-        if (header.category) {
-            const domainHints = extractDomainHints(query);
-            if (domainHints.includes(header.category)) {
-                score += 0.1;
-            }
-        }
-        // Factor 4: Recency boost (0 - 0.15)
-        if (now - header.mtimeMs < recencyWindow) {
-            score += RELEVANT_MEMORIES_CONFIG.RECENCY_BOOST;
-        }
-        return { header, score };
-    });
-    return scored.sort((a, b) => b.score - a.score);
-}
-// ── Content Loading ─────────────────────────────────────────
-/**
- * Load content for selected files with per-file and total byte limits.
- */
-async function loadSelectedContent(scored) {
-    const results = [];
-    let totalBytes = 0;
-    for (const { header, score } of scored) {
-        if (totalBytes >= RELEVANT_MEMORIES_CONFIG.MAX_TOTAL_BYTES)
-            break;
-        try {
-            let content = await readFile(header.filePath, "utf-8");
-            let truncated = false;
-            // Per-file truncation
-            if (content.length > RELEVANT_MEMORIES_CONFIG.MAX_FILE_BYTES) {
-                content = content.slice(0, RELEVANT_MEMORIES_CONFIG.MAX_FILE_BYTES)
-                    + `\n\n> [Truncated at ${RELEVANT_MEMORIES_CONFIG.MAX_FILE_BYTES} bytes. Use memory tool read_file for full content: ${header.filename}]`;
-                truncated = true;
-            }
-            // Total budget check
-            const contentBytes = Buffer.byteLength(content, "utf-8");
-            if (totalBytes + contentBytes > RELEVANT_MEMORIES_CONFIG.MAX_TOTAL_BYTES) {
-                // Truncate to fit remaining budget
-                const remaining = RELEVANT_MEMORIES_CONFIG.MAX_TOTAL_BYTES - totalBytes;
-                content = content.slice(0, remaining)
-                    + `\n\n> [Truncated to fit session budget. Use memory tool read_file for full content: ${header.filename}]`;
-                truncated = true;
-            }
-            totalBytes += Buffer.byteLength(content, "utf-8");
-            results.push({
-                filename: header.filename,
-                filePath: header.filePath,
-                mtimeMs: header.mtimeMs,
-                score,
-                content,
-                truncated,
-            });
-        }
-        catch { /* skip unreadable */ }
-    }
-    return results;
-}
-// ── Helpers ─────────────────────────────────────────────────
-/**
- * Tokenize text into lowercase words (Chinese + English).
- */
-function tokenize(text) {
-    // Split on whitespace + CJK boundaries + punctuation
-    return text
-        .toLowerCase()
-        .replace(/[^\w\u4e00-\u9fff]+/g, " ")
-        .split(/\s+/)
-        .filter(w => w.length > 1);
-}
-/**
- * Infer memory category from filename prefix convention.
- * E.g. "lesson-docker.md" → "lesson", "project-foo.md" → "project"
- */
-function inferCategory(filename) {
-    const name = filename.replace(/\.md$/, "");
-    const prefixes = ["lesson", "project", "pattern", "preference", "fact", "decision", "task", "reference"];
-    for (const prefix of prefixes) {
-        if (name.startsWith(prefix + "-") || name.startsWith(prefix + "_")) {
-            return prefix;
-        }
-    }
-    return null;
-}
-/**
- * Extract domain hints from query for category alignment scoring.
- */
-function extractDomainHints(query) {
-    const hints = [];
-    const lower = query.toLowerCase();
-    if (/(?:bug|error|fix|debug|issue|问题|报错|修复)/.test(lower))
-        hints.push("lesson");
-    if (/(?:architecture|设计|架构|决定|decision)/.test(lower))
-        hints.push("decision");
-    if (/(?:pattern|convention|惯例|标准|practice)/.test(lower))
-        hints.push("pattern");
-    if (/(?:prefer|style|偏好|风格|习惯)/.test(lower))
-        hints.push("preference");
-    if (/(?:deploy|port|config|version|部署|配置|环境)/.test(lower))
-        hints.push("fact");
-    if (/(?:project|repo|codebase|项目|仓库)/.test(lower))
-        hints.push("project");
-    if (/(?:task|todo|plan|任务|计划)/.test(lower))
-        hints.push("task");
-    if (/(?:api|doc|guide|reference|文档|手册)/.test(lower))
-        hints.push("reference");
-    return hints;
-}
-/**
- * Format relevant memories as a single block for system prompt injection.
- * CC parity: includes freshness header per file.
- */
-export function formatRelevantMemoriesBlock(memories) {
-    if (memories.length === 0)
-        return "";
-    const now = Date.now();
-    const sections = memories.map(m => {
-        const age = Math.floor((now - m.mtimeMs) / (24 * 60 * 60 * 1000));
-        const freshness = age === 0 ? "today" : age === 1 ? "yesterday" : `${age} days ago`;
-        return `## Memory (saved ${freshness}): ${m.filename}\n\n${m.content}`;
-    });
-    return sections.join("\n\n---\n\n");
-}

package/dist/runtime/memory/implicit-extraction.d.ts

@@ -1,58 +0,0 @@
-/**
- * Implicit Memory Extraction — CC extractMemories lightweight port.
- *
- * Architecture:
- *   Layer 1: Zero-cost signal detection (regex) — decides if turn has extractable content
- *   Layer 2: Lightweight LLM pass (async, non-blocking) — extracts structured facts
- *
- * This runs AFTER turn.end, so the user already has their response.
- * Layer 2 only fires for ~10-20% of turns (those with detectable signals).
- *
- * Reference: claude-code src/services/extractMemories/extractMemories.ts
- */
-import type { MemoryWriter } from "../ports/memory-writer.js";
-export interface ExtractedFact {
-    text: string;
-    category: "personal_fact" | "preference" | "event" | "lesson" | "pattern" | "decision";
-    importance: number;
-    eventDate?: string;
-}
-export interface ImplicitExtractionDeps {
-    /** Local memory provider for writing extracted facts. */
-    localProvider: MemoryWriter;
-    /** User ID. */
-    userId: string;
-    /** Logger. */
-    log: {
-        debug(msg: string): void;
-        warn(msg: string): void;
-    };
-    /**
-     * LLM invocation function (uses background/cheap model).
-     * Returns structured JSON string or null if unavailable.
-     */
-    llmExtract?: (prompt: string) => Promise<string | null>;
-}
-export interface TurnPair {
-    userMessage: string;
-    assistantMessage: string;
-}
-/**
- * Layer 1: Detect if a user message contains signals worth extracting.
- * Zero LLM cost — pure regex scanning.
- *
- * @returns true if the message likely contains extractable personal facts/events
- */
-export declare function hasExtractionSignal(userMessage: string): boolean;
-/**
- * Layer 2: Use a lightweight LLM to extract structured facts from a turn pair.
- * Only called when Layer 1 signals are detected.
- */
-export declare function extractFactsViaLlm(turn: TurnPair, llmExtract: (prompt: string) => Promise<string | null>, today: string): Promise<ExtractedFact[]>;
-/**
- * Run the full implicit extraction pipeline for a completed turn.
- * This is async and non-blocking — call it after turn.end.
- *
- * @returns Number of facts extracted and stored
- */
-export declare function runImplicitExtraction(turn: TurnPair, deps: ImplicitExtractionDeps): Promise<number>;

package/dist/runtime/memory/implicit-extraction.js

@@ -1,187 +0,0 @@
-/**
- * Implicit Memory Extraction — CC extractMemories lightweight port.
- *
- * Architecture:
- *   Layer 1: Zero-cost signal detection (regex) — decides if turn has extractable content
- *   Layer 2: Lightweight LLM pass (async, non-blocking) — extracts structured facts
- *
- * This runs AFTER turn.end, so the user already has their response.
- * Layer 2 only fires for ~10-20% of turns (those with detectable signals).
- *
- * Reference: claude-code src/services/extractMemories/extractMemories.ts
- */
-// ── Layer 1: Signal Detection (zero-cost regex) ─────────────
-/**
- * Signal words that indicate a turn MAY contain extractable personal facts/events.
- * These are broader than the explicit "记住" patterns — they detect IMPLICIT value.
- *
- * Categories:
- *   - Financial: income, salary, budget
- *   - Life events: moving, job change, birthday, illness
- *   - Achievements: published, launched, completed, passed
- *   - Temporal markers: today/yesterday/this week + action verbs
- *   - Personal state: diagnosed, pregnant, married, graduated
- */
-const SIGNAL_PATTERNS = [
-    // Chinese financial signals
-    /(?:收入|工资|薪资|月薪|年薪|到账|报销|预算|存款|花了|赚了|亏了)\s*[\d.]+/,
-    // Chinese life events
-    /(?:搬家|换工作|离职|入职|跳槽|结婚|离婚|怀孕|生了|去世|住院|出院|手术)/,
-    // Chinese achievements
-    /(?:上线了|发布了|完成了|通过了|考上了|拿到了|录取|获奖|毕业|结业|答辩)/,
-    // Chinese temporal + action (e.g., "今天面试了", "昨天提交了")
-    /(?:今天|昨天|前天|上周|这周|上个月|这个月).*?(?:了|完|好|过)/,
-    // Chinese personal identity markers
-    /(?:我是|我叫|我在|我住|我的(?:工作|职业|专业|公司|学校))/,
-    // Chinese relationship/family
-    /(?:我(?:老婆|老公|女朋友|男朋友|爸|妈|儿子|女儿|孩子))/,
-    // English financial
-    /(?:salary|income|earned|spent|budget|savings?)\s*(?:is|was|of)?\s*[\d$¥€£]/i,
-    // English life events
-    /(?:moved to|got (?:married|divorced|promoted|fired|hired)|graduated|diagnosed)/i,
-    // English achievements
-    /(?:launched|published|shipped|released|completed|passed|got accepted)/i,
-    // English personal
-    /(?:my (?:name|job|company|school|major|birthday|anniversary) (?:is|was))/i,
-];
-/**
- * Layer 1: Detect if a user message contains signals worth extracting.
- * Zero LLM cost — pure regex scanning.
- *
- * @returns true if the message likely contains extractable personal facts/events
- */
-export function hasExtractionSignal(userMessage) {
-    // Only scan first 600 chars (signals are typically at the start)
-    const snippet = userMessage.slice(0, 600);
-    return SIGNAL_PATTERNS.some(p => p.test(snippet));
-}
-// ── Layer 2: LLM Extraction ─────────────────────────────────
-const EXTRACTION_PROMPT = `You are a memory extraction assistant. Analyze the following conversation turn and extract any personal facts, events, or preferences worth remembering long-term.
-
-Rules:
-- Only extract FACTS about the user (not the assistant)
-- Convert relative dates to absolute (e.g., "今天" → "2026-05-25")
-- Each fact should be a single, atomic statement
-- Skip trivial/transient information (e.g., "帮我写个代码" is NOT a fact)
-- Importance: 0.5=routine, 0.7=notable, 0.9=significant life event
-
-User message:
-{user_message}
-
-Assistant response:
-{assistant_message}
-
-Today's date: {today}
-
-Respond ONLY with a JSON array (or empty array [] if nothing worth extracting):
-[{"text": "...", "category": "personal_fact|preference|event|lesson", "importance": 0.5-0.9, "eventDate": "YYYY-MM-DD or null"}]`;
-/**
- * Layer 2: Use a lightweight LLM to extract structured facts from a turn pair.
- * Only called when Layer 1 signals are detected.
- */
-export async function extractFactsViaLlm(turn, llmExtract, today) {
-    const prompt = EXTRACTION_PROMPT
-        .replace("{user_message}", turn.userMessage.slice(0, 1000))
-        .replace("{assistant_message}", turn.assistantMessage.slice(0, 500))
-        .replace("{today}", today);
-    try {
-        const response = await llmExtract(prompt);
-        if (!response)
-            return [];
-        // Parse JSON from response (handle markdown code blocks)
-        const jsonStr = response.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
-        const parsed = JSON.parse(jsonStr);
-        if (!Array.isArray(parsed))
-            return [];
-        // Validate and sanitize
-        return parsed
-            .filter((item) => item.text &&
-            typeof item.text === "string" &&
-            item.text.length >= 5 &&
-            item.text.length <= 500 &&
-            item.category)
-            .map((item) => ({
-            text: item.text.trim(),
-            category: validateCategory(item.category),
-            importance: Math.min(0.9, Math.max(0.3, Number(item.importance) || 0.5)),
-            eventDate: typeof item.eventDate === "string" ? item.eventDate : undefined,
-        }))
-            .slice(0, 3); // Max 3 facts per turn
-    }
-    catch {
-        return [];
-    }
-}
-function validateCategory(cat) {
-    const valid = new Set(["personal_fact", "preference", "event", "lesson", "pattern", "decision"]);
-    return valid.has(cat) ? cat : "personal_fact";
-}
-// ── Combined Pipeline ───────────────────────────────────────
-/**
- * Run the full implicit extraction pipeline for a completed turn.
- * This is async and non-blocking — call it after turn.end.
- *
- * @returns Number of facts extracted and stored
- */
-export async function runImplicitExtraction(turn, deps) {
-    // Layer 1: Signal detection
-    if (!hasExtractionSignal(turn.userMessage)) {
-        return 0;
-    }
-    deps.log.debug(`implicit-extract: signal detected in user message (${turn.userMessage.slice(0, 50)}...)`);
-    // Layer 2: LLM extraction (if available)
-    if (!deps.llmExtract) {
-        deps.log.debug("implicit-extract: no LLM extractor configured, skipping Layer 2");
-        return 0;
-    }
-    const today = new Date().toISOString().slice(0, 10);
-    const facts = await extractFactsViaLlm(turn, deps.llmExtract, today);
-    if (facts.length === 0) {
-        deps.log.debug("implicit-extract: LLM returned no facts");
-        return 0;
-    }
-    // Ordinary background extraction submits proposals; final L2 claims are owned
-    // by the consolidation pipeline.
-    let stored = 0;
-    for (const fact of facts) {
-        try {
-            if (!deps.localProvider.proposeExtracted) {
-                continue;
-            }
-            const result = await deps.localProvider.proposeExtracted([{
-                    text: fact.text,
-                    category: fact.category,
-                    importance: fact.importance,
-                }], deps.userId, {
-                source: "implicit-extract",
-            });
-            if ((result.proposalsAdded ?? 0) > 0) {
-                stored++;
-                deps.log.debug(`implicit-extract: proposed "${fact.text.slice(0, 60)}..." [${fact.category}]`);
-                // Event continuity: if this is an event, find and boost related memories
-                if (fact.category === "event") {
-                    try {
-                        const related = deps.localProvider.findRelatedEvents
-                            ? await deps.localProvider.findRelatedEvents(fact.text, deps.userId)
-                            : [];
-                        for (const r of related) {
-                            // Boost importance of related events (they form a chain)
-                            deps.localProvider.feedback?.([r.id], "useful").catch(() => { });
-                        }
-                        if (related.length > 0) {
-                            deps.log.debug(`implicit-extract: linked to ${related.length} related events`);
-                        }
-                    }
-                    catch { /* non-fatal */ }
-                }
-            }
-            else {
-                deps.log.debug(`implicit-extract: dedup skipped "${fact.text.slice(0, 40)}..."`);
-            }
-        }
-        catch {
-            // Non-fatal
-        }
-    }
-    return stored;
-}

package/dist/runtime/memory/recall-category-filter.d.ts

@@ -1,54 +0,0 @@
-import type { QMemoryCategory } from "./categories.js";
-/** Detected query scenario with preferred categories. */
-export interface RecallCategoryHint {
-    /** Detected scenario label. */
-    scenario: QueryScenario;
-    /** Preferred categories for this scenario (ordered by priority). */
-    preferred: QMemoryCategory[];
-    /** Categories to deprioritize (still recalled but scored lower). */
-    deprioritized: QMemoryCategory[];
-    /** Confidence of scenario detection (0.0-1.0). */
-    confidence: number;
-}
-/** Known query scenarios. */
-export type QueryScenario = "coding" | "config" | "conversation" | "learning" | "decision" | "general";
-/**
- * Detect the query scenario and return category preferences.
- *
- * Uses pattern matching on the user query to infer intent.
- * Returns "general" (no filtering) when confidence is below threshold.
- *
- * @param query - User query text
- * @returns Category hint with preferred/deprioritized categories
- */
-export declare function detectRecallCategories(query: string): RecallCategoryHint;
-/**
- * Apply category boost/penalty to a recall score.
- *
- * Used by recall hooks to adjust memory scores based on category alignment.
- *
- * @param baseScore - Original relevance score (0.0-1.0)
- * @param memoryCategory - Category of the memory entry (if known)
- * @param hint - Category hint from detectRecallCategories()
- * @returns Adjusted score
- */
-export declare function applyCategoryBoost(baseScore: number, memoryCategory: string | undefined | null, hint: RecallCategoryHint): number;
-/**
- * Filter and re-rank a list of recalled memories based on category preferences.
- *
- * @param memories - Raw recalled memories with optional category
- * @param hint - Category hint from detectRecallCategories()
- * @param minScore - Minimum adjusted score to keep (default: 0)
- * @returns Re-ranked memories (highest adjusted score first)
- */
-export declare function filterByCategory<T extends {
-    score?: number;
-    category?: string | null;
-}>(memories: T[], hint: RecallCategoryHint, minScore?: number): T[];
-/**
- * Infer memory category from filename prefix convention.
- * E.g. "lesson-docker.md" → "lesson", "fact-ports.md" → "fact"
- *
- * Exported for use by recall hooks.
- */
-export declare function inferCategoryFromFilename(filename: string): QMemoryCategory | null;