@jack200714/mafw 4.5.1

package/gateway/dist/recall/legacy-t1-archive.js

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.archiveLegacyT1 = archiveLegacyT1;
+// One-time archival of the legacy spiral-*.jsonl T1 observation files (turnID
+// era before the SQLite T1 store). Files move into tier1/archive/ (preserving
+// the goalId subdirectory structure) so nothing is lost. Idempotent via an
+// ARCHIVED marker file.
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("../core/utils/logger");
+function archiveLegacyT1(projectDirs) {
+    let archived = 0;
+    let projects = 0;
+    for (const projectDir of projectDirs) {
+        const tier1 = path.join(projectDir, '.mafw', 'memory', 'tier1');
+        if (!fs.existsSync(tier1))
+            continue;
+        const archive = path.join(tier1, 'archive');
+        if (fs.existsSync(path.join(archive, 'ARCHIVED')))
+            continue;
+        // spiral files live under tier1/<goalId>/ (and legacy flat tier1/).
+        const spiralFiles = [];
+        const scan = (dir, relDir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.name === 'archive')
+                    continue;
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    scan(full, path.join(relDir, entry.name));
+                else if (entry.name.endsWith('.jsonl'))
+                    spiralFiles.push({ from: full, rel: path.join(relDir, entry.name) });
+            }
+        };
+        scan(tier1, '');
+        if (spiralFiles.length === 0)
+            continue;
+        try {
+            for (const f of spiralFiles) {
+                const dest = path.join(archive, f.rel);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.renameSync(f.from, dest);
+            }
+            fs.writeFileSync(path.join(archive, 'ARCHIVED'), new Date().toISOString(), 'utf-8');
+            archived += spiralFiles.length;
+            projects++;
+            logger_1.log.info(`[t1-archive] moved ${spiralFiles.length} legacy spiral files to ${archive}`);
+        }
+        catch (err) {
+            logger_1.log.warn(`[t1-archive] failed for ${tier1}: ${err.message}`);
+        }
+    }
+    return { archived, projects };
+}

package/gateway/dist/recall/memory-worker.js

@@ -0,0 +1,128 @@
+"use strict";
+// Persistent LLM execution channel for the memory pipelines. One long-lived
+// gateway-internal session per worker, lazily created and reused (mirrors the
+// /api/llm/compress pattern but uses the synchronous `session.prompt` so the
+// caller gets the extracted text back). Failure invalidates the cached session
+// so the next call re-creates it; sessions rotate periodically to keep the
+// accumulated history (and its token cost) bounded.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryWorker = void 0;
+class MemoryWorker {
+    client;
+    opts;
+    sessionId = null;
+    label;
+    promptCount = 0;
+    lastPromptAt = 0;
+    constructor(client, opts) {
+        this.client = client;
+        this.opts = opts;
+        this.label = opts.label ?? 'memory-worker';
+    }
+    /** Lazily (re)create the worker session. Persistent: no rotation — the same
+     *  session is reused for every prompt; only failures / serve restarts
+     *  invalidate it. Throws on failure — caller decides fallback. */
+    async ensureSession() {
+        if (this.sessionId)
+            return this.sessionId;
+        const created = await this.client.session.create({ directory: this.opts.directory });
+        this.sessionId = created?.id ?? null;
+        if (!this.sessionId)
+            throw new Error('memory worker: failed to create session');
+        console.log(`[MemoryWorker] ${this.label} created session ${this.sessionId}`);
+        this.opts.onSessionCreated?.(this.sessionId);
+        return this.sessionId;
+    }
+    /**
+     * Compact the session after an idle period to bound the per-prompt token cost.
+     * Uses opencode's native session.summarize() so the system prefix and recent
+     * context survive. Falls back to rotation (dispose + recreate) on failure.
+     */
+    async maybeCompact(sessionId, model) {
+        const compactIdleMs = this.opts.compactIdleMs ?? 8 * 60 * 60 * 1000;
+        if (compactIdleMs <= 0)
+            return;
+        if (this.promptCount === 0 || this.lastPromptAt === 0)
+            return;
+        const idleMs = Date.now() - this.lastPromptAt;
+        if (idleMs < compactIdleMs)
+            return;
+        const timeoutMs = this.opts.promptTimeoutMs ?? 120_000;
+        try {
+            const res = await Promise.race([
+                this.client.session.summarize({
+                    sessionID: sessionId,
+                    ...(model ? { providerID: model.providerID, modelID: model.modelID } : {}),
+                }),
+                new Promise((_, reject) => {
+                    const timer = setTimeout(() => reject(new Error(`${this.label}: summarize timed out after ${timeoutMs}ms`)), timeoutMs);
+                    timer.unref?.();
+                }),
+            ]);
+            const ok = res;
+            if (ok === true) {
+                console.log(`[MemoryWorker] ${this.label} compacted session ${sessionId}`);
+            }
+            else {
+                console.log(`[MemoryWorker] ${this.label} summarize returned ${ok}; session ${sessionId} kept`);
+            }
+        }
+        catch (err) {
+            // Summarize failed — rotate this worker session. A fresh session is
+            // cheaper than keeping an ever-growing history.
+            console.warn(`[MemoryWorker] ${this.label} summarize failed, rotating: ${err.message}`);
+            await this.dispose();
+            throw err; // caller sees the prompt-like failure; next prompt creates a new session
+        }
+    }
+    /**
+     * Run one extraction/reflection prompt. Returns the assistant text reply.
+     * Bounded by promptTimeoutMs (default 120s) so a hung LLM call can never
+     * lock the whole pipeline (the action-level guard is skip-once semantics).
+     * Any failure invalidates the cached session and rethrows.
+     */
+    async prompt(message, system, model, agent) {
+        const sessionId = await this.ensureSession();
+        await this.maybeCompact(sessionId, model);
+        const timeoutMs = this.opts.promptTimeoutMs ?? 120_000;
+        try {
+            const result = await Promise.race([
+                this.client.session.prompt({
+                    sessionID: sessionId,
+                    parts: [{ type: 'text', text: message }],
+                    ...(system ? { system } : {}),
+                    ...(model ? { model } : {}),
+                    ...(agent ? { agent } : {}),
+                }),
+                new Promise((_, reject) => {
+                    const timer = setTimeout(() => reject(new Error(`${this.label}: prompt timed out after ${timeoutMs}ms`)), timeoutMs);
+                    timer.unref?.(); // never keep the process alive just for the timeout
+                }),
+            ]);
+            const text = (Array.isArray(result?.parts)
+                ? result.parts.filter((p) => p?.type === 'text').map((p) => p.text).join('\n')
+                : '') || '';
+            this.promptCount++;
+            this.lastPromptAt = Date.now();
+            return text;
+        }
+        catch (err) {
+            this.sessionId = null;
+            throw err;
+        }
+    }
+    async dispose() {
+        if (this.sessionId) {
+            try {
+                await this.client.session.delete({ sessionID: this.sessionId });
+            }
+            catch {
+                // ignore
+            }
+            this.promptCount = 0;
+            this.lastPromptAt = 0;
+            this.sessionId = null;
+        }
+    }
+}
+exports.MemoryWorker = MemoryWorker;

package/gateway/dist/recall/pipeline-rules.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureMemoryPipelineRules = ensureMemoryPipelineRules;
+// Idempotent provisioning of the memory-pipeline cron rules
+// (turn-compress hourly, memory-reflect daily). Fresh installs otherwise have
+// no rules and the pipelines never run.
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("../core/utils/logger");
+const RULES = [
+    { id: 'turn-compress', schedule: '0 * * * *', timezone: 'UTC', action: 'memory:turnCompress' },
+    { id: 'memory-reflect', schedule: '0 3 * * *', timezone: 'UTC', action: 'memory:reflect' },
+    // Daily energy decay — memories fade by elapsed time (0.005/day base rate).
+    { id: 'memory-decay', schedule: '30 3 * * *', timezone: 'UTC', action: 'memory:decay' },
+    // Weekly stale-memory verification — the curator re-checks high-value
+    // procedural/semantic memories against the live environment (read-only
+    // probes) and supersedes contradicted ones (env-probing curation).
+    { id: 'memory-review', schedule: '0 4 * * 0', timezone: 'UTC', action: 'memory:review' },
+];
+function ensureMemoryPipelineRules(mafwDir) {
+    const dir = path.join(mafwDir, 'automations');
+    for (const rule of RULES) {
+        const file = path.join(dir, `${rule.id}.json`);
+        if (fs.existsSync(file))
+            continue;
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, JSON.stringify({
+                id: rule.id,
+                enabled: true,
+                trigger: { type: 'cron', schedule: rule.schedule, timezone: rule.timezone },
+                action: { type: rule.action },
+                skill: '',
+                args: {},
+                onResult: { type: 'goal' },
+            }, null, 2), 'utf-8');
+            logger_1.log.info(`[Scheduler] provisioned pipeline rule ${rule.id}`);
+        }
+        catch (err) {
+            logger_1.log.warn(`[Scheduler] failed to provision rule ${rule.id}: ${err.message}`);
+        }
+    }
+}

package/gateway/dist/recall/recall-context.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blobPenalty = blobPenalty;
+exports.searchRecallMemories = searchRecallMemories;
+exports.mergeScanResults = mergeScanResults;
+exports.searchRecallMemoriesSync = searchRecallMemoriesSync;
+const config_1 = require("../config");
+const logger_1 = require("../core/utils/logger");
+/**
+ * Detect multi-hop/comparison questions that need facts from multiple sessions.
+ * Returns sub-queries that decompose the question into independent searches.
+ */
+function decomposeMultiHopQuery(query) {
+    const lower = query.toLowerCase();
+    const subQueries = [];
+    // Comparison patterns: "how much older/younger", "difference between", "compare", "vs"
+    const isComparison = /\b(how much|what is the|difference between|compare|vs\.?|older|younger|more|less|bigger|smaller|higher|lower|faster|slower|better|worse)\b/i.test(query);
+    // Temporal/aggregation: "average", "total", "sum", "count", "when did"
+    const hasAggregation = /\b(average|total|sum|count|how many|how often|when did|what time|which)\b/i.test(query);
+    if (isComparison || hasAggregation) {
+        // Extract noun phrases as entity candidates
+        // Simple heuristic: words that are not common question words
+        const questionWords = new Set(['how', 'what', 'when', 'where', 'why', 'which', 'who', 'whom', 'whose', 'is', 'are', 'was', 'were', 'do', 'does', 'did', 'have', 'has', 'had', 'can', 'could', 'will', 'would', 'should', 'may', 'might', 'shall', 'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by', 'from', 'as', 'into', 'than', 'that', 'this', 'these', 'those', 'it', 'its', 'my', 'your', 'our', 'their', 'his', 'her', 'i', 'me', 'we', 'you', 'they', 'he', 'she']);
+        const words = lower.replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter(w => w.length >= 2 && !questionWords.has(w));
+        // Sub-query 1: personal/user info patterns
+        const userPatterns = words.filter(w => /\b(age|birthday|born|live|work|job|salary|income|family|married|single|children|kid|pet|car|house|home|school|college|university|degree|major|hobby|interest|preference|like|dislike|favorite|eat|drink|travel|visit|read|watch|listen)\b/.test(w));
+        if (userPatterns.length > 0) {
+            subQueries.push('user ' + userPatterns.join(' '));
+        }
+        // Sub-query 2: entity/topic patterns  
+        const entityWords = words.filter(w => !userPatterns.includes(w));
+        if (entityWords.length > 0) {
+            subQueries.push(entityWords.join(' '));
+        }
+        // Sub-query 3: the full noun phrase (without question words)
+        if (words.length >= 2) {
+            subQueries.push(words.join(' '));
+        }
+    }
+    return subQueries.slice(0, 4); // Cap at 4 sub-queries
+}
+/**
+ * Extract key entities from a query for cross-session topic linking.
+ * Looks for quoted strings, camelCase/PascalCase identifiers, ALL_CAPS words,
+ * common technical terms, and natural language entity nouns.
+ */
+function extractQueryEntities(query) {
+    const entities = [];
+    // Quoted strings (e.g., "React", 'auth module')
+    const quoted = query.match(/['"]([^'"]+)['"]/g);
+    if (quoted) {
+        for (const q of quoted) {
+            const inner = q.slice(1, -1).trim();
+            if (inner.length >= 2)
+                entities.push(inner);
+        }
+    }
+    // camelCase/PascalCase identifiers (e.g., "getUserAuth", "AuthModule")
+    const camelPascal = query.match(/\b[A-Z][a-z]+(?:[A-Z][a-z]+)+\b/g);
+    if (camelPascal) {
+        for (const c of camelPascal) {
+            entities.push(c);
+            // Also add split version: "getUserAuth" -> "get User Auth"
+            const split = c.replace(/([a-z])([A-Z])/g, '$1 $2');
+            if (split !== c)
+                entities.push(split);
+        }
+    }
+    // ALL_CAPS words (e.g., "API", "URL", "HTTP")
+    const allCaps = query.match(/\b[A-Z]{2,}\b/g);
+    if (allCaps) {
+        for (const a of allCaps) {
+            if (a.length >= 2 && !['THE', 'AND', 'FOR', 'NOT', 'BUT', 'ARE', 'WAS', 'HAS', 'CAN', 'DID', 'DOES'].includes(a)) {
+                entities.push(a);
+            }
+        }
+    }
+    // Natural language entity nouns (common content words that appear in memories)
+    const lower = query.toLowerCase();
+    const nlEntities = lower.match(/\b(?:age|birthday|salary|income|department|employee|manager|team|company|project|product|feature|service|server|database|api|endpoint|config|setting|preference|language|framework|library|tool|plugin|extension|theme|template|pattern|convention|standard|protocol|interface|model|schema|type|class|function|method|module|package|library|framework|component|file|directory|path|url|link|user|admin|role|permission|access|session|token|auth|oauth|jwt|deploy|build|test|debug|error|exception|log|monitor|metric|alert|notification|webhook|cron|schedule|timer|cache|queue|stack|tree|graph|node|edge|list|map|set|dict|array|string|number|boolean|null|undefined|true|false|yes|no|ok|done|failed|success|pending|active|inactive|enabled|disabled|public|private|internal|external|local|remote|global|shared|custom|default|primary|secondary|main|sub|child|parent|root|head|tail|first|last|next|prev|current|old|new|temporary|permanent)\b/g);
+    if (nlEntities) {
+        for (const e of nlEntities) {
+            if (e.length >= 3 && !entities.includes(e)) {
+                entities.push(e);
+            }
+        }
+    }
+    // Deduplicate and return (case-insensitive dedup)
+    const seen = new Set();
+    const unique = [];
+    for (const e of entities) {
+        const lower = e.toLowerCase();
+        if (!seen.has(lower) && lower.length >= 2) {
+            seen.add(lower);
+            unique.push(e);
+        }
+    }
+    return unique.slice(0, 10); // Cap at 10 entities
+}
+/**
+ * Expand a query by searching for entity-related memories.
+ * Uses both entity extraction and multi-hop decomposition to catch
+ * cross-session topic links that BM25 might miss.
+ */
+function expandQuery(index, query, pushed, topK = 3) {
+    const expandedScores = new Map();
+    const accumulate = (hits, weight) => {
+        const norms = maxNormalize(hits.map(h => h.score));
+        hits.forEach((h, i) => {
+            if (pushed.has(h.entry.id) || h.entry.superseded_by)
+                return;
+            const existing = expandedScores.get(h.entry.id) || 0;
+            expandedScores.set(h.entry.id, existing + norms[i] * weight);
+        });
+    };
+    // Strategy 1: entity-based expansion (individual entity searches)
+    const entities = extractQueryEntities(query);
+    for (const entity of entities) {
+        const hits = fetchScored(index, entity, topK, {});
+        accumulate(hits, 0.4);
+    }
+    // Strategy 2: multi-hop decomposition (sub-query searches)
+    const subQueries = decomposeMultiHopQuery(query);
+    for (const sq of subQueries) {
+        const hits = fetchScored(index, sq, topK, {});
+        accumulate(hits, 0.35);
+    }
+    // Sort by accumulated score
+    return [...expandedScores.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK * 2);
+}
+/** Multi-topic blob abstraction (chained MinHash merges) 鈥?dilutes precision. */
+function blobPenalty(abstraction) {
+    const segs = (abstraction || '').split('|').map(s => s.trim()).filter(Boolean).length;
+    return segs >= 4 ? 0.5 : 1;
+}
+/**
+ * Max-normalize scores to [0,1] (score/max). Deliberately NOT min-max: min-max
+ * stretches the weakest candidate to 0, which makes any multiplicative penalty
+ * unable to flip order among few candidates and exaggerates raw-score gaps.
+ */
+function maxNormalize(values) {
+    if (values.length === 0)
+        return [];
+    const max = Math.max(...values);
+    if (max <= 0)
+        return values.map(() => 0);
+    return values.map(v => v / max);
+}
+/** Fetch scored candidates preferring searchScored (raw scores) with a legacy search() fallback. */
+function fetchScored(index, query, topK, options) {
+    if (typeof index.searchScored === 'function') {
+        return index.searchScored(query, topK, { retriever: options.retriever ?? 'bm25' }) || [];
+    }
+    return (index.search(query, topK, options) || []).map((e) => ({ entry: e, score: 0.5 }));
+}
+/**
+ * Search recall memories using BM25 + query expansion. This is the *sync*
+ * recall path (<50ms): the plugin-side client aborts after 100ms, so the
+ * index scan must never be awaited here 鈥?its results arrive via async
+ * prefetch snapshots merged by mergeScanResults() instead.
+ *
+ * Scoring: candidate-set-normalized BM25 脳 blob penalty as the base; expansion
+ * hits add norm 脳 0.4 per entity; scan direct/graph hits get fixed boosts
+ * (0.35 / 0.2). energy no longer doubles as the score.
+ */
+async function searchRecallMemories(index, query, pushed, topK = 3, options = {}) {
+    if (!index)
+        return [];
+    const scored = fetchScored(index, query, topK * 2, options)
+        .filter((s) => s.entry && !pushed.has(s.entry.id) && !s.entry.superseded_by);
+    const norms = maxNormalize(scored.map((s) => s.score));
+    const resultMap = new Map();
+    scored.forEach((s, i) => {
+        resultMap.set(s.entry.id, {
+            id: s.entry.id,
+            primary_abstraction: s.entry.primary_abstraction || '',
+            memory_value: s.entry.memory_value || s.entry.content || '',
+            energy: s.entry.energy || 0,
+            score: norms[i] * blobPenalty(s.entry.primary_abstraction),
+            type: s.entry.type,
+            created_at: s.entry.created_at,
+            source: 'bm25',
+        });
+    });
+    // Query expansion: entity / sub-query hits join with a RELATIVE weight
+    // (norm 脳 0.4, capped) instead of flat energy 鈥?wide blobs no longer rack
+    // up multiples of a constant.
+    const expandedResults = expandQuery(index, query, pushed, topK);
+    for (const exp of expandedResults) {
+        if (resultMap.has(exp.id))
+            continue; // Already from BM25 鈥?don't override
+        const entry = index.getIndex?.()?.entries?.find((e) => e.id === exp.id);
+        if (!entry || entry.superseded_by)
+            continue;
+        resultMap.set(exp.id, {
+            id: exp.id,
+            primary_abstraction: entry.primary_abstraction || '',
+            memory_value: entry.memory_value || entry.content || '',
+            energy: entry.energy || 0,
+            score: exp.score * blobPenalty(entry.primary_abstraction),
+            type: entry.type,
+            created_at: entry.created_at,
+            source: 'expansion',
+        });
+    }
+    // Merge scan results if a prefetch snapshot is provided (never awaited 鈥?
+    // snapshots are precomputed, so this is a pure in-memory operation).
+    const scanSnapshot = options.scanSnapshot;
+    if (scanSnapshot && scanSnapshot.relevantIds.length > 0) {
+        const expanded = mergeScanResults(resultMap, scanSnapshot, index, pushed);
+        logger_1.log.info(`[Recall] bm25=${scored.length} scan=${scanSnapshot.relevantIds.length} expanded=${expanded} union=${resultMap.size} confidence=${scanSnapshot.confidence}`);
+    }
+    // Sort by score descending, then slice to topK
+    const results = [...resultMap.values()]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK);
+    return results;
+}
+/**
+ * Merge precomputed scan results into a recall result map: anchor-graph 1-hop
+ * expansion, dedup against BM25 (BM25 wins, direct scan hits get a +0.3 boost,
+ * graph neighbors +0.15). Pure function over in-memory data 鈥?safe to call on
+ * the sync recall path with a prefetch snapshot.
+ */
+function mergeScanResults(resultMap, scanResult, index, pushed) {
+    const indexEntries = index?.getIndex?.()?.entries || [];
+    // Anchor graph 1-hop expansion: for each scan-selected ID, bring in its
+    // graph neighbors. This catches multi-session relationships that the
+    // scan alone might miss (e.g., scan picks "restaurant" but not "hotel
+    // near the restaurant" 鈥?the graph edge connects them).
+    const graphStore = index?.getAnchorGraphStore?.();
+    const expandedIds = new Set(scanResult.relevantIds);
+    if (graphStore) {
+        for (const id of scanResult.relevantIds) {
+            try {
+                const neighbors = graphStore.getNeighbors([id], config_1.config.search.graph.maxNeighbors, new Set(scanResult.relevantIds));
+                for (const [nbId] of neighbors) {
+                    expandedIds.add(nbId);
+                }
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    let expandedCount = 0;
+    for (const id of expandedIds) {
+        if (resultMap.has(id)) {
+            // Already from BM25 鈥?mark as 'both'
+            resultMap.get(id).source = 'both';
+            continue;
+        }
+        if (pushed.has(id))
+            continue;
+        const entry = indexEntries.find((e) => e.id === id);
+        if (!entry || entry.superseded_by)
+            continue;
+        expandedCount++;
+        const isDirectScan = scanResult.relevantIds.includes(id);
+        const boost = isDirectScan ? 0.35 : 0.2;
+        resultMap.set(id, {
+            id: entry.id,
+            primary_abstraction: entry.primary_abstraction || '',
+            memory_value: entry.memory_value || entry.content || '',
+            energy: entry.energy || 0,
+            score: boost * blobPenalty(entry.primary_abstraction),
+            type: entry.type,
+            created_at: entry.created_at,
+            source: isDirectScan ? 'scan' : 'scan+graph',
+        });
+    }
+    return expandedCount;
+}
+/**
+ * Synchronous BM25-only search (backward compatible).
+ * Used by step injection and other latency-sensitive paths.
+ * Shares the normalized scoring with the async variant.
+ */
+function searchRecallMemoriesSync(index, query, pushed, topK = 3, options = {}) {
+    if (!index)
+        return [];
+    const scored = fetchScored(index, query, topK * 2, options)
+        .filter((s) => s.entry && !pushed.has(s.entry.id) && !s.entry.superseded_by)
+        .slice(0, topK);
+    const norms = maxNormalize(scored.map((s) => s.score));
+    return scored.map((s, i) => ({
+        id: s.entry.id,
+        primary_abstraction: s.entry.primary_abstraction || '',
+        memory_value: s.entry.memory_value || s.entry.content || '',
+        energy: s.entry.energy || 0,
+        score: norms[i] * blobPenalty(s.entry.primary_abstraction),
+        type: s.entry.type,
+        created_at: s.entry.created_at,
+        source: 'bm25',
+    })).sort((a, b) => b.score - a.score);
+}

package/gateway/dist/recall/reflect-cursor.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReflectCursor = exports.MAX_IDS_PER_SESSION = void 0;
+exports.MAX_IDS_PER_SESSION = 500;
+const SCOPE = 'reflect-cursor';
+class ReflectCursor {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    reflectedIds(sessionID) {
+        const ids = this.db.kvGet(SCOPE, sessionID);
+        return new Set(Array.isArray(ids) ? ids : []);
+    }
+    isReflected(sessionID, id) {
+        const ids = this.db.kvGet(SCOPE, sessionID);
+        return Array.isArray(ids) && ids.includes(id);
+    }
+    /** Mark ids as reflected (atomic single-row upsert). */
+    markReflected(sessionID, ids) {
+        if (ids.length === 0)
+            return;
+        const existing = this.db.kvGet(SCOPE, sessionID) ?? [];
+        const seen = new Set(existing);
+        for (const id of ids) {
+            if (!seen.has(id)) {
+                seen.add(id);
+                existing.push(id);
+            }
+        }
+        // bound the list (prune oldest beyond the cap)
+        const trimmed = existing.length > exports.MAX_IDS_PER_SESSION ? existing.slice(-exports.MAX_IDS_PER_SESSION) : existing;
+        this.db.kvSet(SCOPE, sessionID, trimmed);
+    }
+    /** Drop ids that no longer exist in the index (best-effort maintenance). */
+    prune(liveIds) {
+        for (const { key, value } of this.db.kvAll(SCOPE)) {
+            if (!Array.isArray(value))
+                continue;
+            const kept = value.filter((id) => liveIds.has(id));
+            if (kept.length !== value.length) {
+                if (kept.length === 0)
+                    this.db.kvDelete(SCOPE, key);
+                else
+                    this.db.kvSet(SCOPE, key, kept);
+            }
+        }
+    }
+}
+exports.ReflectCursor = ReflectCursor;