qlogicagent 2.13.3 → 2.13.5

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

@@ -0,0 +1,270 @@
+// ============================================================
+// 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

@@ -0,0 +1,58 @@
+/**
+ * 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

@@ -0,0 +1,187 @@
+/**
+ * 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

@@ -0,0 +1,54 @@
+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;