qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/hooks/memory-hooks.js

@@ -0,0 +1,356 @@
+// ============================================================
+// Memory lifecycle hooksCLI runtime
+//
+// Wires memory.before_recall / memory.after_recall hook points
+// into the qmemory REST API. Registered once per session when
+// the HookRegistry is created.
+//
+// CC parity enhancements:
+//   - LRU dedup: tracks surfaced memory paths, skips duplicates
+//   - Session byte limit: stops injecting after 60KB total
+//   - Async prefetch: non-blocking, abort-aware
+//
+// Reference: claude-code src/utils/attachments.ts
+//            startRelevantMemoryPrefetch + filterDuplicateMemoryAttachments
+// ============================================================
+import { findRelevantMemories, formatRelevantMemoriesBlock } from "../memory/find-relevant-memories.js";
+import { applyCategoryBoost, inferCategoryFromFilename } from "../memory/recall-category-filter.js";
+import { hasExtractionSignal, runImplicitExtraction } from "../memory/implicit-extraction.js";
+import { MEMORY_PREFETCH_MAX_SESSION_BYTES, MEMORY_PREFETCH_LIMIT_PER_RECALL, MEMORY_MAX_SURFACED_ENTRIES, } from "../config/tunable-defaults.js";
+// ── Configuration (CC RELEVANT_MEMORIES_CONFIG parity) ──────
+export const MEMORY_PREFETCH_CONFIG = {
+    MAX_SESSION_BYTES: MEMORY_PREFETCH_MAX_SESSION_BYTES,
+    LIMIT_PER_RECALL: MEMORY_PREFETCH_LIMIT_PER_RECALL,
+    MAX_SURFACED_ENTRIES: MEMORY_MAX_SURFACED_ENTRIES,
+};
+/**
+ * Create a fresh memory prefetch state (once per session).
+ */
+export function createMemoryPrefetchState() {
+    return { surfacedPaths: new Set(), sessionBytes: 0 };
+}
+/**
+ * Register memory lifecycle hooks on the HookRegistry.
+ *
+ * Hook points wired:
+ *   - memory.before_recall: prefetch context from qmemory (query-based)
+ *   - memory.after_recall: log recall results
+ *
+ * CC parity additions:
+ *   - LRU dedup via surfacedPaths (filterDuplicateMemoryAttachments)
+ *   - Session byte limit (MAX_SESSION_BYTES = 60KB)
+ *   - Async prefetch (non-blocking promise, abort-aware)
+ *
+ * Returns a cleanup function to unregister.
+ */
+export function registerMemoryHooks(hooks, deps, 
+/** Shared statepass the same object across hook re-registrations in a session. */
+prefetchState) {
+    const cleanups = [];
+    const state = prefetchState ?? createMemoryPrefetchState();
+    // Shared recall cache per turn (avoids redundant queries)
+    let lastRecallTurnId;
+    let lastRecallResults = [];
+    // memory.before_recallprefetch from qmemory with dedup + byte limit
+    cleanups.push(hooks.register({
+        point: "memory.before_recall",
+        priority: 50,
+        label: "qmemory-prefetch",
+        handler: async (_point, ctx) => {
+            if (!deps.memoryProvider || !ctx.query) {
+                return { action: "continue", context: ctx };
+            }
+            // CC MAX_SESSION_BYTES parity: stop injecting after budget exhausted
+            if (state.sessionBytes >= MEMORY_PREFETCH_CONFIG.MAX_SESSION_BYTES) {
+                deps.log.debug("memory.before_recall: session byte budget exhausted, skipping");
+                return { action: "continue", context: ctx };
+            }
+            try {
+                const results = await deps.memoryProvider.search(ctx.query, deps.userId, {
+                    limit: MEMORY_PREFETCH_CONFIG.LIMIT_PER_RECALL,
+                });
+                // CC filterDuplicateMemoryAttachments parity: LRU dedup
+                const dedupedResults = results.filter((r) => {
+                    const entry = r;
+                    const key = entry.path ?? entry.id ?? "";
+                    if (!key)
+                        return true;
+                    if (state.surfacedPaths.has(key))
+                        return false;
+                    // Check byte budget before accepting
+                    const entryBytes = (entry.content?.length ?? 0) * 2; // rough UTF-16 estimate
+                    if (state.sessionBytes + entryBytes > MEMORY_PREFETCH_CONFIG.MAX_SESSION_BYTES) {
+                        return false;
+                    }
+                    // Accept: track in LRU + byte count
+                    state.surfacedPaths.add(key);
+                    state.sessionBytes += entryBytes;
+                    // LRU eviction: keep set bounded
+                    if (state.surfacedPaths.size > MEMORY_PREFETCH_CONFIG.MAX_SURFACED_ENTRIES) {
+                        const oldest = state.surfacedPaths.values().next().value;
+                        if (oldest !== undefined)
+                            state.surfacedPaths.delete(oldest);
+                    }
+                    return true;
+                });
+                lastRecallTurnId = ctx.turnId;
+                lastRecallResults = dedupedResults;
+                deps.log.debug(`memory.before_recall: prefetched ${results.length} -> ${dedupedResults.length} after dedup (${state.sessionBytes} bytes used)`);
+                // Return recalled memories via enriched context for injection
+                let recalledMemories = dedupedResults.map((r) => {
+                    const entry = r;
+                    return {
+                        text: entry.text ?? entry.content ?? "",
+                        score: entry.score,
+                        category: entry.metadata?.category ?? null,
+                        source: "l2-long-term",
+                        label: "L2 long-term",
+                    };
+                }).filter(m => m.text);
+                // P6: Apply category boost/penalty based on query scenario
+                if (ctx.preferredCategories?.length || ctx.deprioritizedCategories?.length) {
+                    const hint = {
+                        scenario: "general",
+                        preferred: (ctx.preferredCategories ?? []),
+                        deprioritized: (ctx.deprioritizedCategories ?? []),
+                        confidence: 1.0,
+                    };
+                    recalledMemories = recalledMemories
+                        .map(m => ({ ...m, score: applyCategoryBoost(m.score ?? 0.5, m.category, hint) }))
+                        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+                }
+                // Relevance threshold: discard memories with score below minimum
+                // This prevents low-quality matches from polluting context
+                const RELEVANCE_THRESHOLD = 0.15;
+                recalledMemories = recalledMemories.filter(m => (m.score ?? 0) >= RELEVANCE_THRESHOLD);
+                return {
+                    action: "continue",
+                    context: {
+                        ...ctx,
+                        recalledMemories: [...(ctx.recalledMemories ?? []), ...recalledMemories],
+                    },
+                };
+            }
+            catch (err) {
+                deps.log.warn(`memory.before_recall: qmemory prefetch failed: ${err instanceof Error ? err.message : String(err)}`);
+                lastRecallResults = [];
+            }
+            return { action: "continue", context: ctx };
+        },
+    }));
+    // memory.after_recalllog results
+    cleanups.push(hooks.register({
+        point: "memory.after_recall",
+        priority: 50,
+        label: "qmemory-recall-log",
+        handler: (_point, ctx) => {
+            const count = lastRecallTurnId === ctx.turnId ? lastRecallResults.length : 0;
+            deps.log.debug(`memory.after_recall: ${ctx.blockCount ?? 0} blocks assembled, ${count} qmemory results (session: ${state.sessionBytes} bytes)`);
+            return { action: "continue", context: ctx };
+        },
+    }));
+    // ── Auto-extract: detect explicit "remember" intent from user messages ──
+    // Zero LLM cost — pure regex heuristic. Only fires if localMemoryProvider is available.
+    if (deps.localMemoryProvider) {
+        cleanups.push(hooks.register({
+            point: "turn.completed",
+            priority: 90, // Low priority, runs after everything else
+            label: "memory-auto-extract",
+            handler: async (_point, _ctx) => {
+                const msg = deps.getLastUserMessage?.();
+                if (!msg)
+                    return { action: "continue", context: _ctx };
+                // Only extract from explicit user intent (not every turn)
+                const extracted = extractExplicitMemoryIntents(msg);
+                if (extracted.length === 0)
+                    return { action: "continue", context: _ctx };
+                for (const item of extracted) {
+                    try {
+                        const result = (await deps.localMemoryProvider.addText(item.text, deps.userId, {
+                            source: "auto-extract",
+                            category: item.category,
+                            importance: 0.6,
+                        }));
+                        if ((result?.memoriesAdded ?? 0) > 0) {
+                            deps.log.debug(`memory-auto-extract: stored "${item.text.slice(0, 50)}..." (${item.category})`);
+                        }
+                        else {
+                            // Fail-loud: explicit user "remember" intent did NOT become a
+                            // searchable memory (deferred/merged/conflicted in consolidation).
+                            deps.log.warn(`memory-auto-extract: "${item.text.slice(0, 50)}..." was NOT committed as a memory ` +
+                                `(memoriesAdded=0) — check consolidation pipeline status`);
+                        }
+                    }
+                    catch (err) {
+                        deps.log.warn(`memory-auto-extract: failed to store "${item.text.slice(0, 50)}...": ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                return { action: "continue", context: _ctx };
+            },
+        }));
+        // ── Implicit extraction (Layer 1 signal + Layer 2 LLM) ──
+        // Fires AFTER auto-extract (priority 95). Non-blocking background task.
+        // Only runs if: (a) auto-extract didn't match, (b) signal words detected, (c) LLM available.
+        cleanups.push(hooks.register({
+            point: "turn.completed",
+            priority: 95,
+            label: "memory-implicit-extract",
+            handler: async (_point, _ctx) => {
+                const userMsg = deps.getLastUserMessage?.();
+                if (!userMsg)
+                    return { action: "continue", context: _ctx };
+                // Skip if auto-extract already handled this turn (explicit patterns)
+                const explicitExtracted = extractExplicitMemoryIntents(userMsg);
+                if (explicitExtracted.length > 0) {
+                    return { action: "continue", context: _ctx };
+                }
+                // Layer 1: signal detection (zero cost)
+                if (!hasExtractionSignal(userMsg)) {
+                    return { action: "continue", context: _ctx };
+                }
+                // Layer 2: LLM extraction (async, fire-and-forget)
+                const assistantMsg = deps.getLastAssistantMessage?.();
+                if (!assistantMsg || !deps.llmExtract) {
+                    return { action: "continue", context: _ctx };
+                }
+                // Non-blocking: don't await, let it run in background
+                void runImplicitExtraction({ userMessage: userMsg, assistantMessage: assistantMsg }, {
+                    localProvider: deps.localMemoryProvider,
+                    userId: deps.userId,
+                    log: deps.log,
+                    llmExtract: deps.llmExtract,
+                }).catch(() => { });
+                return { action: "continue", context: _ctx };
+            },
+        }));
+    }
+    return () => {
+        for (const cleanup of cleanups)
+            cleanup();
+        lastRecallResults = [];
+    };
+}
+/**
+ * Register the MEMDIR cross-file recall hook on `memory.before_recall`.
+ *
+ * - Priority 40 (before QMemory at 50)
+ * - Scans topic files, selects top-5 relevant
+ * - Injects content into recalledMemories (merged with QMemory results)
+ * - Respects session byte budget from shared MemoryPrefetchState
+ * - Dedup via surfacedPaths (shared with QMemory hook)
+ */
+export function registerMemdirRecallHook(hooks, deps, prefetchState) {
+    const state = prefetchState ?? createMemoryPrefetchState();
+    const cleanup = hooks.register({
+        point: "memory.before_recall",
+        priority: 40,
+        label: "memdir-cross-file-recall",
+        handler: async (_point, ctx) => {
+            const memorySource = deps.getMemorySource();
+            if (!memorySource || !ctx.query) {
+                return { action: "continue", context: ctx };
+            }
+            // Respect shared session byte budget
+            if (state.sessionBytes >= MEMORY_PREFETCH_CONFIG.MAX_SESSION_BYTES) {
+                deps.log.debug("memdir-recall: session byte budget exhausted, skipping");
+                return { action: "continue", context: ctx };
+            }
+            try {
+                const memoryDir = memorySource.getRootPath();
+                let relevant = await findRelevantMemories(ctx.query, memoryDir, state.surfacedPaths);
+                if (relevant.length === 0) {
+                    return { action: "continue", context: ctx };
+                }
+                // P6: Apply category boost/penalty based on query scenario
+                if (ctx.preferredCategories?.length || ctx.deprioritizedCategories?.length) {
+                    const hint = {
+                        scenario: "general",
+                        preferred: (ctx.preferredCategories ?? []),
+                        deprioritized: (ctx.deprioritizedCategories ?? []),
+                        confidence: 1.0,
+                    };
+                    relevant = relevant
+                        .map(r => ({
+                        ...r,
+                        score: applyCategoryBoost(r.score, inferCategoryFromFilename(r.filename), hint),
+                    }))
+                        .sort((a, b) => b.score - a.score);
+                }
+                // Track surfaced paths + byte budget (shared with QMemory hook)
+                const accepted = relevant.filter(r => {
+                    const bytes = Buffer.byteLength(r.content, "utf-8");
+                    if (state.sessionBytes + bytes > MEMORY_PREFETCH_CONFIG.MAX_SESSION_BYTES) {
+                        return false;
+                    }
+                    state.surfacedPaths.add(r.filePath);
+                    state.sessionBytes += bytes;
+                    return true;
+                });
+                if (accepted.length === 0) {
+                    return { action: "continue", context: ctx };
+                }
+                deps.log.debug(`memdir-recall: found ${relevant.length} -> accepted ${accepted.length} files (${state.sessionBytes} bytes used)`);
+                // Format as recalled memories (compatible with existing injection path)
+                const block = formatRelevantMemoriesBlock(accepted);
+                const existing = ctx.recalledMemories ?? [];
+                const memdirMemories = [{
+                        text: block,
+                        score: 0.9,
+                        category: "project",
+                        source: "l1-project-md",
+                        label: "L1 project MD",
+                    }];
+                return {
+                    action: "continue",
+                    context: { ...ctx, recalledMemories: [...memdirMemories, ...existing] },
+                };
+            }
+            catch (err) {
+                deps.log.warn(`memdir-recall: cross-file recall failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return { action: "continue", context: ctx };
+        },
+    });
+    return cleanup;
+}
+// ── Auto-extract heuristic helpers ─────────────────────────
+/**
+ * Detect explicit memory-storage intent in user messages.
+ * Zero LLM cost — pure regex patterns for phrases like:
+ *   "记住...", "remember that...", "note: ...", "我的偏好是..."
+ *
+ * Only triggers on EXPLICIT user intent. Does NOT try to extract
+ * from every message (that would require an LLM call).
+ */
+const REMEMBER_PATTERNS = [
+    // Chinese explicit patterns
+    { pattern: /(?:请|帮我)?记住[：:]\s*(.+)/i, category: "personal_fact", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /(?:请|帮我)?记住(.{10,120})/i, category: "personal_fact", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /我的偏好[是为：:]\s*(.+)/i, category: "preference", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /我(?:喜欢|偏好|习惯)(.{5,100})/i, category: "preference", extractor: (m) => `用户偏好: ${m[1]?.trim()}` },
+    { pattern: /以后(?:都|请|要)(.{5,100})/i, category: "preference", extractor: (m) => `用户要求: ${m[1]?.trim()}` },
+    // English explicit patterns
+    { pattern: /remember(?:\s+(?:that|this))?(?:\s+for\s+future\s+turns)?\s*[:：]\s*(.+)/i, category: "personal_fact", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /(?:note|memo)\s*[:：]\s*(.+)/i, category: "lesson", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /my preference is\s*[:：]?\s*(.+)/i, category: "preference", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /remember(?:\s+that)?[：:]\s*(.+)/i, category: "personal_fact", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /(?:note|memo)[：:]\s*(.+)/i, category: "lesson", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /my preference is[：:]?\s*(.+)/i, category: "preference", extractor: (m) => m[1]?.trim() || null },
+    { pattern: /i (?:always|prefer|like to|want you to)\s+(.{10,120})/i, category: "preference", extractor: (m) => `User preference: ${m[1]?.trim()}` },
+];
+function extractExplicitMemoryIntents(message) {
+    const results = [];
+    // Only check the first 500 chars to avoid false positives in long messages
+    const snippet = message.slice(0, 500);
+    for (const { pattern, category, extractor } of REMEMBER_PATTERNS) {
+        const match = snippet.match(pattern);
+        if (match) {
+            const text = extractor(match, snippet);
+            if (text && text.length >= 5 && text.length <= 300) {
+                results.push({ text, category });
+                break; // One extraction per message max
+            }
+        }
+    }
+    return results;
+}

package/dist/runtime/hooks/skill-recall-hooks.d.ts

@@ -0,0 +1,37 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { CommunityDiscoveryCoordinator } from "../community/community-discovery-coordinator.js";
+export declare const SKILL_RECALL_CONFIG: {
+    readonly MAX_RECALLED_SKILLS: 3;
+    readonly MAX_SKILL_CONTENT_CHARS: 800;
+    readonly CACHE_TTL_MS: number;
+};
+/**
+ * Detect whether user message contains retrospective/cross-reference semantics
+ * OR similar-task patterns that could benefit from existing skills.
+ * Returns extracted keywords for skill matching if triggered, or null.
+ */
+export declare function detectRetrospectiveTrigger(message: string): string[] | null;
+export interface SkillRecallHooksDeps {
+    /** Current project cwd (to exclude from cross-project search). */
+    currentCwd?: string;
+    /** Optional online community discovery coordinator. */
+    communityDiscovery?: CommunityDiscoveryCoordinator | null;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+/**
+ * Register the cross-project skill recall hook on `memory.before_recall`.
+ * Runs at lower priority (60) than QMemory prefetch (50) so it supplements,
+ * not replaces, the standard memory recall.
+ *
+ * When triggered, injects cross-project skill metadata into recalledMemories.
+ */
+export declare function registerSkillRecallHooks(hooks: HookRegistry, deps: SkillRecallHooksDeps): () => void;
+/**
+ * Invalidate the cross-project skill index cache.
+ * Call when skills are created/deleted/promoted to refresh.
+ */
+export declare function invalidateSkillRecallCache(): void;

package/dist/runtime/hooks/skill-recall-hooks.js

@@ -0,0 +1,263 @@
+// ============================================================
+// Cross-Project Skill Recall — Passive recall + LLM guidance.
+//
+// When a user's message contains retrospective semantics (e.g.,
+// "之前做过", "参考 XX 项目", "didn't you do this before"),
+// this hook scans skills from OTHER known projects and injects
+// matching skill metadata into the recall context. The LLM then
+// decides whether to invoke/promote/copy the skill.
+//
+// This is read-only — it never writes to other projects' skill dirs.
+// ============================================================
+import * as fs from "node:fs";
+import { resolveSkills } from "../infra/skill-resolver.js";
+import { SKILL_RECALL_MAX_SKILLS, SKILL_RECALL_MAX_CONTENT_CHARS, SKILL_RECALL_CACHE_TTL_MS, } from "../config/tunable-defaults.js";
+// ── Configuration (re-exported for backward compat) ─────────
+export const SKILL_RECALL_CONFIG = {
+    MAX_RECALLED_SKILLS: SKILL_RECALL_MAX_SKILLS,
+    MAX_SKILL_CONTENT_CHARS: SKILL_RECALL_MAX_CONTENT_CHARS,
+    CACHE_TTL_MS: SKILL_RECALL_CACHE_TTL_MS,
+};
+// ── Retrospective trigger patterns ─────────────────────────
+/**
+ * Detect whether user message contains retrospective/cross-reference semantics
+ * OR similar-task patterns that could benefit from existing skills.
+ * Returns extracted keywords for skill matching if triggered, or null.
+ */
+export function detectRetrospectiveTrigger(message) {
+    // Chinese patterns — retrospective
+    const zhRetrospective = [
+        /之前.{0,8}(?:做过|写过|实现过|处理过|用过|搞过|弄过)/,
+        /以前.{0,8}(?:做过|写过|实现过|处理过|用过)/,
+        /(?:上次|上回|之前|以前).{0,12}(?:不是|是不是|已经).{0,8}(?:做|写|实现|处理)/,
+        /(?:参考|参照|照着|按照).{0,6}(?:项目|工程|仓库)/,
+        /(?:那个|那边|另一个).{0,6}(?:项目|工程).{0,6}(?:里|中|的)/,
+        /(?:跟|和|像).{0,6}(?:项目|工程).{0,6}(?:一样|类似|差不多)/,
+        /(?:复用|重用|搬过来|拿过来|移过来|copy过来)/,
+    ];
+    // Chinese patterns — similar task (broadened)
+    const zhSimilarTask = [
+        /(?:有没有|有无|是否有).{0,6}(?:技能|skill|模板|template|现成的)/,
+        /(?:能不能|可以).{0,6}(?:自动|像之前|快速).{0,6}(?:生成|创建|写|做)/,
+        /(?:跟|和|类似|像).{0,4}(?:上次|之前|其他|那个).{0,4}(?:一样|类似)/,
+        /(?:批量|自动化|一键).{0,6}(?:生成|创建|部署|处理)/,
+        /(?:同样的|相同的|一样的).{0,4}(?:方式|方法|流程|步骤)/,
+    ];
+    // English patterns — retrospective
+    const enRetrospective = [
+        /(?:before|previously|earlier|last time).{0,20}(?:did|done|made|built|implemented|wrote)/i,
+        /(?:didn't|did) you.{0,15}(?:already|before|earlier)/i,
+        /(?:same|similar).{0,10}(?:as|to|like).{0,10}(?:project|repo)/i,
+        /(?:reuse|re-use|copy from|bring over|port from).{0,15}(?:project|repo)/i,
+        /(?:remember|recall).{0,10}(?:doing|making|building|writing)/i,
+        /(?:other|another|different)\s+project/i,
+    ];
+    // English patterns — similar task (broadened)
+    const enSimilarTask = [
+        /(?:is there|do you have|any).{0,10}(?:skill|template|automation|workflow)/i,
+        /(?:like|similar to|same as).{0,15}(?:last time|before|the other)/i,
+        /(?:automate|batch|bulk).{0,10}(?:create|generate|process|build)/i,
+        /(?:can you|could you).{0,10}(?:do the same|repeat|replicate)/i,
+    ];
+    const allPatterns = [...zhRetrospective, ...zhSimilarTask, ...enRetrospective, ...enSimilarTask];
+    const triggered = allPatterns.some(p => p.test(message));
+    if (!triggered)
+        return null;
+    // Extract keywords for matching (simple: take nouns/verbs from the message)
+    const keywords = extractMatchKeywords(message);
+    return keywords.length > 0 ? keywords : null;
+}
+/**
+ * Extract keywords from a retrospective message for skill matching.
+ * Focuses on domain terms, skipping common filler words.
+ */
+function extractMatchKeywords(message) {
+    // Remove common Chinese retrospective trigger words to get actual content words
+    const cleaned = message
+        .replace(/之前|以前|上次|上回|不是|是不是|已经|做过|写过|实现过|处理过|用过|搞过|弄过/g, " ")
+        .replace(/参考|参照|照着|按照|项目|工程|仓库|那个|那边|另一个|里|中|的|跟|和|像|一样|类似|差不多/g, " ")
+        .replace(/复用|重用|搬过来|拿过来|移过来/g, " ")
+        // English stopwords
+        .replace(/\b(the|a|an|is|was|were|did|didn't|do|you|i|we|it|this|that|before|previously|earlier|last|time|already|same|similar|as|to|like|from|project|repo|remember|recall|doing|making|building|writing|other|another|different)\b/gi, " ")
+        .trim();
+    // Tokenize and filter short/empty tokens
+    const tokens = cleaned
+        .split(/[\s,;.!?，。！？、；：""''（）\[\]{}]+/)
+        .filter(t => t.length >= 2)
+        .map(t => t.toLowerCase());
+    return [...new Set(tokens)].slice(0, 8);
+}
+let cachedIndex = null;
+let cacheTimestamp = 0;
+/**
+ * Build or retrieve cached index of recallable skills — skills present in the
+ * single global store but NOT active in the current project (project-scoped
+ * skills the user may want to invoke or enable here).
+ */
+function getSkillIndex(currentCwd) {
+    const now = Date.now();
+    if (cachedIndex && (now - cacheTimestamp) < SKILL_RECALL_CONFIG.CACHE_TTL_MS) {
+        return cachedIndex;
+    }
+    const index = [];
+    for (const s of resolveSkills(currentCwd)) {
+        if (s.active)
+            continue; // already active in this project — no need to recall
+        let content;
+        try {
+            content = fs.readFileSync(s.filePath, "utf8");
+        }
+        catch {
+            continue; // unreadable — skip
+        }
+        const firstLines = content.split("\n").slice(0, 5).join(" ").toLowerCase();
+        index.push({
+            name: s.name,
+            projectDir: s.baseDir,
+            projectName: "skill store",
+            content,
+            searchText: `${s.name.toLowerCase()} ${firstLines}`,
+        });
+    }
+    cachedIndex = index;
+    cacheTimestamp = now;
+    return index;
+}
+/**
+ * Search cross-project skills by keywords.
+ * Returns skills sorted by relevance (number of keyword matches).
+ */
+function searchCrossProjectSkills(keywords, excludeCwd) {
+    if (keywords.length === 0)
+        return [];
+    const index = getSkillIndex(excludeCwd);
+    if (index.length === 0)
+        return [];
+    // Score each skill by keyword match count
+    const scored = index.map(skill => {
+        let score = 0;
+        for (const kw of keywords) {
+            if (skill.searchText.includes(kw))
+                score += 2;
+            if (skill.name.includes(kw))
+                score += 3; // Name match is stronger
+        }
+        return { skill, score };
+    });
+    return scored
+        .filter(s => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, SKILL_RECALL_CONFIG.MAX_RECALLED_SKILLS)
+        .map(s => s.skill);
+}
+/**
+ * Register the cross-project skill recall hook on `memory.before_recall`.
+ * Runs at lower priority (60) than QMemory prefetch (50) so it supplements,
+ * not replaces, the standard memory recall.
+ *
+ * When triggered, injects cross-project skill metadata into recalledMemories.
+ */
+export function registerSkillRecallHooks(hooks, deps) {
+    const cleanup = hooks.register({
+        point: "memory.before_recall",
+        priority: 60, // After QMemory (50), supplementary
+        label: "cross-project-skill-recall",
+        handler: async (_point, ctx) => {
+            const query = ctx.query;
+            if (!query)
+                return { action: "continue", context: ctx };
+            const communityDiscovery = await discoverCommunitySkill(query, deps);
+            const communityMemories = communityDiscovery
+                ? [communityDiscoveryMemory(communityDiscovery)]
+                : [];
+            // Step 1: Detect retrospective trigger
+            const keywords = detectRetrospectiveTrigger(query);
+            if (!keywords) {
+                if (communityMemories.length === 0) {
+                    return { action: "continue", context: ctx };
+                }
+                return {
+                    action: "continue",
+                    context: {
+                        ...ctx,
+                        recalledMemories: [...(ctx.recalledMemories ?? []), ...communityMemories],
+                    },
+                };
+            }
+            deps.log.debug(`skill-recall: retrospective trigger detected, keywords: [${keywords.join(", ")}]`);
+            // Step 2: Search cross-project skills
+            const matches = searchCrossProjectSkills(keywords, deps.currentCwd);
+            if (matches.length === 0) {
+                deps.log.debug("skill-recall: no cross-project skill matches found");
+                return { action: "continue", context: ctx };
+            }
+            deps.log.debug(`skill-recall: found ${matches.length} cross-project skill(s): ${matches.map(m => `${m.name}@${m.projectName}`).join(", ")}`);
+            // Step 3: Build recall entries
+            const existingMemories = ctx.recalledMemories ?? [];
+            const skillMemories = matches.map(skill => {
+                const truncatedContent = skill.content.length > SKILL_RECALL_CONFIG.MAX_SKILL_CONTENT_CHARS
+                    ? skill.content.slice(0, SKILL_RECALL_CONFIG.MAX_SKILL_CONTENT_CHARS) + "\n...(truncated)"
+                    : skill.content;
+                return {
+                    text: [
+                        `[Skill available in your store] Skill "${skill.name}" is in your skill store but not active in this project:`,
+                        truncatedContent,
+                        `→ To use it now: skill tool with action "invoke" name "${skill.name}"`,
+                        `→ To make it available across all projects: skill tool with action "promote" name "${skill.name}"`,
+                        `→ Or just follow the instructions above directly`,
+                    ].join("\n"),
+                    source: "skill",
+                    label: "Skill",
+                    score: 0.85, // High confidence — explicit retrospective request
+                };
+            });
+            return {
+                action: "continue",
+                context: {
+                    ...ctx,
+                    recalledMemories: [...existingMemories, ...communityMemories, ...skillMemories],
+                },
+            };
+        },
+    });
+    return cleanup;
+}
+/**
+ * Invalidate the cross-project skill index cache.
+ * Call when skills are created/deleted/promoted to refresh.
+ */
+export function invalidateSkillRecallCache() {
+    cachedIndex = null;
+    cacheTimestamp = 0;
+}
+async function discoverCommunitySkill(query, deps) {
+    if (!deps.communityDiscovery)
+        return null;
+    const result = await deps.communityDiscovery.matchForTurn(query);
+    if (result.status === "matched" || result.status === "cached")
+        return result;
+    if (result.status === "unavailable") {
+        deps.log.debug(`skill-recall: community discovery unavailable (${result.error ?? "unknown"})`);
+    }
+    return null;
+}
+function communityDiscoveryMemory(result) {
+    const match = result.match;
+    const cached = result.cacheEntry;
+    const resourceId = match?.id ?? cached?.resourceId ?? "";
+    const title = match?.title ?? cached?.title ?? resourceId;
+    const summary = match?.summary ?? cached?.summary ?? "";
+    const sourceTier = match?.sourceTier ?? cached?.sourceTier ?? "community";
+    const riskTier = match?.effectiveRiskTier ?? cached?.effectiveRiskTier ?? "unknown";
+    return {
+        text: [
+            `[Community skill available] "${title}" (${resourceId})`,
+            `Summary: ${summary}`,
+            `Source: ${sourceTier}; effective risk: ${riskTier}`,
+            "Use community.resolveInstall before any install. Do not inject or execute package contents from discovery.",
+        ].join("\n"),
+        source: "community",
+        label: "Community",
+        score: result.status === "matched" ? 0.74 : 0.68,
+    };
+}

package/dist/runtime/hooks/skill-recall-hooks.test.d.ts

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