cogmem 3.6.2

package/dist/recall/RecallExplanation.d.ts

@@ -0,0 +1,59 @@
+import type { MemoryKernel, MemoryKernelNavigationResult } from '../factory.js';
+import type { MemoryEventContext, MemorySourceRef } from '../types/index.js';
+import { type AgentRecallDecisionTrace } from '../agent/AgentMemoryBackend.js';
+import type { AgentRecallQueryPlan } from '../agent/AgentRecallQueryCompiler.js';
+import { type RecallGovernanceSuppressionReason } from './RecallGovernance.js';
+export interface RecallExplanationOptions {
+    query: string;
+    projectId?: string;
+    agentId?: string;
+    collection?: string;
+    limit?: number;
+    startTime?: number;
+    endTime?: number;
+}
+export interface RecallExplanationEvidence {
+    id: string;
+    text: string;
+    projectId?: string;
+    topicPath?: string;
+    tags: string[];
+    source?: string;
+    sourceAnchor?: RecallExplanationSourceAnchor;
+    activationPath?: string[];
+    whyMatched?: string[];
+}
+export interface RecallExplanationFilteredEvidence {
+    id: string;
+    text?: string;
+    projectId?: string;
+    tags: string[];
+    source?: string;
+    sourceAnchor?: RecallExplanationSourceAnchor;
+    reason: 'agent_scope_mismatch' | 'collection_scope_mismatch' | 'over_context_limit' | 'status_suppressed';
+    governanceReason?: RecallGovernanceSuppressionReason;
+}
+export interface RecallExplanationSourceAnchor {
+    eventId: string;
+    sourceEventType?: string;
+    sourceRefs: MemorySourceRef[];
+    context?: MemoryEventContext;
+}
+export interface RecallExplanation {
+    query: string;
+    projectId?: string;
+    agentId?: string;
+    collection?: string;
+    recallMode: MemoryKernelNavigationResult['recallMode'] | 'raw_ledger_fallback';
+    fallbackUsed: boolean;
+    narrative?: NonNullable<MemoryKernelNavigationResult['navigation']>['narrative'];
+    pulseTrace?: NonNullable<MemoryKernelNavigationResult['navigation']>['pulse']['trace'];
+    temporalTraversal?: NonNullable<MemoryKernelNavigationResult['navigation']>['branchSearch']['temporalTraversal'];
+    runtime?: NonNullable<MemoryKernelNavigationResult['navigation']>['runtime'];
+    evidence: RecallExplanationEvidence[];
+    filteredEvidence?: RecallExplanationFilteredEvidence[];
+    queryPlan?: AgentRecallQueryPlan;
+    decisionTrace?: AgentRecallDecisionTrace;
+}
+export declare function explainRecallWithKernel(kernel: MemoryKernel, options: RecallExplanationOptions): RecallExplanation;
+//# sourceMappingURL=RecallExplanation.d.ts.map

package/dist/recall/RecallExplanation.js

@@ -0,0 +1,244 @@
+import { KernelAgentMemoryBackend, } from '../agent/AgentMemoryBackend.js';
+import { isRecallableMemoryEvidence, recallGovernanceReasonsFor, recallSuppressionReasonFor, } from './RecallGovernance.js';
+export function explainRecallWithKernel(kernel, options) {
+    const limit = Math.max(1, options.limit ?? 8);
+    if (options.agentId) {
+        const projectId = options.projectId || options.agentId;
+        const retrievalLimit = Math.max(limit * 4, 24);
+        const agentRecall = new KernelAgentMemoryBackend(kernel).recall({
+            agentId: options.agentId,
+            projectId,
+            collection: options.collection,
+            query: options.query,
+            limit,
+            startTime: options.startTime,
+            endTime: options.endTime,
+        });
+        const navigated = kernel.navigateMemory(options.query, {
+            projectId,
+            limit: retrievalLimit,
+            startTime: options.startTime,
+            endTime: options.endTime,
+        });
+        const agentScoped = navigated.rawEvidence.filter((neuron) => isInAgentScope(neuron, options.agentId));
+        const scoped = agentScoped.filter((neuron) => isInCollectionScope(neuron, options.collection));
+        const scopedRecallable = scoped.filter((neuron) => isRecallableMemoryEvidence(neuron));
+        const filteredEvidence = uniqueFilteredEvidence([
+            ...toNavigationFilteredEvidence(navigated, kernel),
+            ...scoped
+                .filter((neuron) => !isRecallableMemoryEvidence(neuron))
+                .map((neuron) => toFilteredEvidence(neuron, 'status_suppressed', undefined, kernel)),
+            ...navigated.rawEvidence
+                .filter((neuron) => !isInAgentScope(neuron, options.agentId))
+                .map((neuron) => toFilteredEvidence(neuron, 'agent_scope_mismatch', undefined, kernel)),
+            ...agentScoped
+                .filter((neuron) => !isInCollectionScope(neuron, options.collection))
+                .map((neuron) => toFilteredEvidence(neuron, 'collection_scope_mismatch', undefined, kernel)),
+            ...scopedRecallable
+                .slice(limit)
+                .map((neuron) => toFilteredEvidence(neuron, 'over_context_limit', undefined, kernel)),
+        ]);
+        return {
+            query: options.query,
+            projectId: options.projectId,
+            agentId: options.agentId,
+            collection: normalizedCollection(options.collection),
+            recallMode: agentRecall.recallMode,
+            fallbackUsed: agentRecall.fallbackUsed,
+            narrative: agentRecall.narrative,
+            pulseTrace: agentRecall.pulseTrace,
+            temporalTraversal: agentRecall.temporalTraversal,
+            runtime: agentRecall.runtime,
+            evidence: agentRecall.items.map((item) => toAgentEvidence(item, agentRecall.decisionTrace, options.agentId, kernel)),
+            filteredEvidence,
+            queryPlan: agentRecall.queryPlan,
+            decisionTrace: agentRecall.decisionTrace,
+        };
+    }
+    const retrievalLimit = Math.max(limit * 4, 24);
+    const navigated = kernel.navigateMemory(options.query, {
+        projectId: options.projectId,
+        limit: retrievalLimit,
+        startTime: options.startTime,
+        endTime: options.endTime,
+    });
+    const collectionScoped = navigated.rawEvidence.filter((neuron) => isInCollectionScope(neuron, options.collection));
+    const included = collectionScoped.slice(0, limit);
+    const filteredEvidence = uniqueFilteredEvidence([
+        ...toNavigationFilteredEvidence(navigated, kernel),
+        ...navigated.rawEvidence
+            .filter((neuron) => !isInCollectionScope(neuron, options.collection))
+            .map((neuron) => toFilteredEvidence(neuron, 'collection_scope_mismatch', undefined, kernel)),
+        ...collectionScoped
+            .slice(limit)
+            .map((neuron) => toFilteredEvidence(neuron, 'over_context_limit', undefined, kernel)),
+    ]);
+    return {
+        query: options.query,
+        projectId: options.projectId,
+        collection: normalizedCollection(options.collection),
+        recallMode: navigated.recallMode,
+        fallbackUsed: navigated.fallbackUsed,
+        narrative: navigated.navigation?.narrative,
+        pulseTrace: navigated.navigation?.pulse.trace,
+        temporalTraversal: navigated.navigation?.branchSearch.temporalTraversal,
+        runtime: navigated.navigation?.runtime,
+        evidence: included.map((neuron) => toEvidence(neuron, navigated, undefined, kernel)),
+        filteredEvidence,
+    };
+}
+function toAgentEvidence(item, decisionTrace, agentId, kernel) {
+    const whyMatched = new Set([`agent_scope:${agentId}`]);
+    if (item.whyMatched)
+        whyMatched.add(item.whyMatched);
+    if (item.sourceAnchor?.eventId)
+        whyMatched.add('provenance:source_event');
+    return {
+        id: item.id,
+        text: item.text,
+        projectId: item.projectId,
+        topicPath: item.topicPath,
+        tags: item.tags,
+        source: item.source,
+        sourceAnchor: sourceAnchorForAgentItem(item, kernel),
+        activationPath: decisionTrace
+            ? [`agent_recall:${decisionTrace.selectedLane}`, `reason:${decisionTrace.reason}`]
+            : ['agent_recall:unavailable'],
+        whyMatched: Array.from(whyMatched),
+    };
+}
+function sourceAnchorForAgentItem(item, kernel) {
+    if (item.sourceType === 'compiled_memory' || item.sourceType === 'imported_summary') {
+        const neuron = kernel.memoryGraph.getNeuron(item.id);
+        if (neuron) {
+            const semanticAnchor = sourceAnchorFor(neuron, kernel);
+            if (semanticAnchor)
+                return semanticAnchor;
+        }
+    }
+    const eventId = item.sourceAnchor?.eventId;
+    if (!eventId)
+        return undefined;
+    const context = kernel.getEventContext(eventId, { before: 1, after: 1 }) || undefined;
+    const payload = context?.event.payload;
+    const sourceRefs = Array.isArray(payload?.sourceRefs)
+        ? payload.sourceRefs.filter((entry) => Boolean(entry && typeof entry === 'object'))
+        : [];
+    return {
+        eventId,
+        sourceEventType: context?.event.eventType,
+        sourceRefs,
+        context,
+    };
+}
+function isInAgentScope(neuron, agentId) {
+    const tags = neuron.metadata.tags || [];
+    const explicitAgentTags = tags.filter((tag) => tag.startsWith('agent:'));
+    if (explicitAgentTags.length === 0)
+        return true;
+    return explicitAgentTags.includes(`agent:${agentId}`) || tags.includes(agentId);
+}
+function isInCollectionScope(neuron, collection) {
+    const tags = neuron.metadata.tags || [];
+    const collectionTags = tags.filter((tag) => tag.startsWith('collection:'));
+    const requested = normalizedCollection(collection);
+    if (requested) {
+        if (requested === 'anchor' && collectionTags.length === 0)
+            return true;
+        return collectionTags.includes(`collection:${requested}`);
+    }
+    return collectionTags.length === 0 || collectionTags.includes('collection:anchor');
+}
+function normalizedCollection(collection) {
+    const normalized = String(collection || '').trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, '_');
+    return normalized || undefined;
+}
+function toEvidence(neuron, result, agentId, kernel) {
+    return {
+        id: neuron.id,
+        text: neuron.content,
+        projectId: neuron.metadata.projectId,
+        topicPath: neuron.metadata.topicPath,
+        tags: neuron.metadata.tags || [],
+        source: neuron.metadata.filePath || neuron.metadata.sourceEventId,
+        sourceAnchor: sourceAnchorFor(neuron, kernel),
+        activationPath: activationPathFor(result),
+        whyMatched: whyMatchedFor(neuron, result, agentId),
+    };
+}
+function toFilteredEvidence(neuron, reason, governanceReason, kernel) {
+    return {
+        id: neuron.id,
+        text: neuron.content,
+        projectId: neuron.metadata.projectId,
+        tags: neuron.metadata.tags || [],
+        source: neuron.metadata.filePath || neuron.metadata.sourceEventId,
+        sourceAnchor: sourceAnchorFor(neuron, kernel),
+        reason,
+        governanceReason: governanceReason ?? (reason === 'status_suppressed' ? recallSuppressionReasonFor(neuron) : undefined),
+    };
+}
+function toNavigationFilteredEvidence(result, kernel) {
+    return (result.filteredEvidence || []).map((item) => (toFilteredEvidence(item.neuron, item.reason, item.governanceReason, kernel)));
+}
+function sourceAnchorFor(neuron, kernel) {
+    const eventId = neuron.metadata.sourceEventId;
+    if (!eventId || !kernel)
+        return undefined;
+    const context = kernel.getEventContext(eventId, { before: 1, after: 1 }) || undefined;
+    if (!context) {
+        return { eventId, sourceRefs: [] };
+    }
+    const payload = context.event.payload;
+    const sourceRefs = Array.isArray(payload.sourceRefs)
+        ? payload.sourceRefs.filter((item) => Boolean(item && typeof item === 'object'))
+        : [];
+    return {
+        eventId,
+        sourceEventType: context.event.eventType,
+        sourceRefs,
+        context,
+    };
+}
+function uniqueFilteredEvidence(items) {
+    const seen = new Set();
+    const uniqueItems = [];
+    for (const item of items) {
+        const key = `${item.id}:${item.reason}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        uniqueItems.push(item);
+    }
+    return uniqueItems;
+}
+function activationPathFor(result) {
+    const runtimePath = result.navigation?.runtime.path || [];
+    const narrativePath = result.navigation?.narrative.path || [];
+    return runtimePath.length > 0
+        ? runtimePath
+        : narrativePath.length > 0
+            ? narrativePath
+            : [`recall:${result.recallMode}`];
+}
+function whyMatchedFor(neuron, result, agentId) {
+    const reasons = new Set();
+    if (agentId && isInAgentScope(neuron, agentId))
+        reasons.add(`agent_scope:${agentId}`);
+    if (neuron.metadata.sourceEventId)
+        reasons.add('provenance:source_event');
+    for (const reason of recallGovernanceReasonsFor(neuron))
+        reasons.add(reason);
+    if (result.navigation?.pulse.fusedIds.includes(neuron.id))
+        reasons.add('pulse:fused');
+    if (result.navigation?.branchSearch.neuronIds.includes(neuron.id))
+        reasons.add('temporal_branch:candidate');
+    if (result.navigation?.branchSearch.temporalTraversal.neuronIds.includes(neuron.id)) {
+        reasons.add('temporal_traversal:candidate');
+    }
+    for (const reason of result.navigation?.narrative.whyMatched || [])
+        reasons.add(reason);
+    if (reasons.size === 0)
+        reasons.add(`recall_mode:${result.recallMode}`);
+    return Array.from(reasons);
+}

package/dist/recall/RecallGovernance.d.ts

@@ -0,0 +1,10 @@
+import type { Neuron } from '../types/index.js';
+export type RecallGovernanceSuppressionReason = 'archived' | 'operational_noise' | 'imported_summary_support' | 'suspect_llm_inference' | 'suspect_external_tool_observation' | 'suspect_unverified_claim' | 'non_recallable_status';
+export declare function isRecallableMemoryEvidence(neuron: Neuron | null | undefined): neuron is Neuron;
+export declare function recallGovernanceReasonsFor(neuron: Neuron): string[];
+export declare function recallSuppressionReasonFor(neuron: Neuron | null | undefined): RecallGovernanceSuppressionReason | undefined;
+export declare function isRawUserUtteranceEvidence(neuron: Neuron): boolean;
+export declare function isOperationalNoiseMemoryEvidence(neuron: Neuron): boolean;
+export declare function isImportedSummarySupportMemoryEvidence(neuron: Neuron): boolean;
+export declare function isOperationalNoiseText(text: string | null | undefined): boolean;
+//# sourceMappingURL=RecallGovernance.d.ts.map

package/dist/recall/RecallGovernance.js

@@ -0,0 +1,83 @@
+export function isRecallableMemoryEvidence(neuron) {
+    if (!neuron)
+        return false;
+    if (isOperationalNoiseMemoryEvidence(neuron))
+        return false;
+    if (isImportedSummarySupportMemoryEvidence(neuron))
+        return false;
+    const status = neuron.metadata.status ?? 'active';
+    if (status === 'active' || status === 'cold')
+        return true;
+    if (status === 'suspect')
+        return isRawUserUtteranceEvidence(neuron);
+    return false;
+}
+export function recallGovernanceReasonsFor(neuron) {
+    const reasons = [];
+    const status = neuron.metadata.status ?? 'active';
+    if (isRawUserUtteranceEvidence(neuron)) {
+        reasons.push('provenance:raw_user_utterance');
+        if (status === 'suspect')
+            reasons.push('governance:allowed_suspect_raw_evidence');
+    }
+    return reasons;
+}
+export function recallSuppressionReasonFor(neuron) {
+    if (!neuron)
+        return undefined;
+    if (isOperationalNoiseMemoryEvidence(neuron))
+        return 'operational_noise';
+    if (isImportedSummarySupportMemoryEvidence(neuron))
+        return 'imported_summary_support';
+    const status = neuron.metadata.status ?? 'active';
+    if (status === 'active' || status === 'cold')
+        return undefined;
+    if (status === 'suspect' && isRawUserUtteranceEvidence(neuron))
+        return undefined;
+    if (status === 'archived')
+        return 'archived';
+    if (status === 'suspect' && neuron.metadata.sourceType === 'llm_inference')
+        return 'suspect_llm_inference';
+    if (status === 'suspect' && neuron.metadata.sourceType === 'external_tool')
+        return 'suspect_external_tool_observation';
+    if (status === 'suspect')
+        return 'suspect_unverified_claim';
+    return 'non_recallable_status';
+}
+export function isRawUserUtteranceEvidence(neuron) {
+    const tags = neuron.metadata.tags || [];
+    return neuron.metadata.sourceType === 'user_input'
+        && tags.includes('reliability:raw_utterance')
+        && tags.includes('role:user')
+        && (tags.includes('record:raw_utterance') || tags.includes('record:conversation_message'));
+}
+export function isOperationalNoiseMemoryEvidence(neuron) {
+    const tags = neuron.metadata.tags || [];
+    if (tags.some((tag) => (tag === 'operational_noise'
+        || tag === 'record:heartbeat'
+        || tag === 'system:heartbeat'
+        || tag === 'routine:heartbeat'))) {
+        return true;
+    }
+    return isOperationalNoiseText(neuron.content);
+}
+export function isImportedSummarySupportMemoryEvidence(neuron) {
+    const tags = neuron.metadata.tags || [];
+    return tags.includes('governance:imported_summary_support')
+        || (tags.includes('source_class:daily_memory')
+            && tags.includes('provenance:imported_summary'));
+}
+export function isOperationalNoiseText(text) {
+    const normalized = String(text || '').trim().toLowerCase();
+    if (!normalized)
+        return false;
+    return [
+        /\[openclaw heartbeat poll\]/i,
+        /^heartbeat_ok$/i,
+        /\bheartbeat_ok\b/i,
+        /\bheartbeat poll\b/i,
+        /please complete your identity setup/i,
+        /test your telegram bot by searching for it/i,
+        /\broutine system ping\b/i,
+    ].some((pattern) => pattern.test(normalized));
+}

package/dist/recall/RecallSufficiencyGate.d.ts

@@ -0,0 +1,40 @@
+import type { BrainRecallResult } from '../types/BrainRecallResult.js';
+export interface RecallSufficiencyInput {
+    query: string;
+    layer1Result: BrainRecallResult;
+    recentTurns: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+        timestamp: number;
+    }>;
+    projectId?: string;
+}
+export interface RecallSufficiencySignals {
+    coverage: number;
+    topConfidence: number;
+    coReferenceHit: boolean;
+    topicalDriftHit: boolean;
+}
+export interface RecallSufficiencyDecision {
+    sufficient: boolean;
+    reason: string;
+    signals: RecallSufficiencySignals;
+    suggestedFollowupQueries: string[];
+}
+export interface RecallSufficiencyGateConfig {
+    coverageThreshold: number;
+    topConfidenceThreshold: number;
+    maxSuggestedFollowups: number;
+}
+export declare class RecallSufficiencyGate {
+    private readonly config;
+    private readonly compiler;
+    constructor(config?: Partial<RecallSufficiencyGateConfig>);
+    evaluate(input: RecallSufficiencyInput): RecallSufficiencyDecision;
+    private calculateTopConfidence;
+    private detectTopicalDrift;
+    private buildDriftContext;
+    private buildFollowups;
+    private collectEvidenceText;
+}
+//# sourceMappingURL=RecallSufficiencyGate.d.ts.map

package/dist/recall/RecallSufficiencyGate.js

@@ -0,0 +1,208 @@
+import { LocalSemanticCompiler } from '../engine/LocalSemanticCompiler.js';
+const DEFAULT_CONFIG = {
+    coverageThreshold: 0.6,
+    topConfidenceThreshold: 0.4,
+    maxSuggestedFollowups: 3
+};
+const DRIFT_CONTEXT_CHAR_BUDGET = 4000;
+const COREFERENCE_CUES = [
+    '之前',
+    '上次',
+    '刚才',
+    '那个',
+    '还记得',
+    '刚说的',
+    '前面提到',
+    '你说过',
+    'earlier',
+    'you said',
+    'remember when',
+    'before',
+    'previously',
+    'we discussed'
+];
+const TEMPORAL_RELATIVE_CUES = [
+    '昨天',
+    '前天',
+    '上周',
+    '上个月',
+    '之前',
+    '上次',
+    '刚才',
+    'yesterday',
+    'last week',
+    'last month',
+    'earlier',
+    'previously',
+    'before'
+];
+export class RecallSufficiencyGate {
+    config;
+    compiler = new LocalSemanticCompiler();
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    evaluate(input) {
+        const compiled = this.compiler.compileQuery({ text: input.query, projectId: input.projectId });
+        const targets = Array.from(new Set([
+            ...compiled.entities.map((entity) => entity.text),
+            ...compiled.temporalHints.map(String),
+            ...compiled.relativeReferences
+        ].map((item) => item.trim()).filter(Boolean)));
+        const evidenceText = this.collectEvidenceText(input.layer1Result);
+        const missing = targets.filter((target) => !textIncludes(evidenceText, target));
+        const coverage = targets.length === 0 ? 1 : (targets.length - missing.length) / targets.length;
+        const topConfidence = this.calculateTopConfidence(input.layer1Result);
+        const coReferenceHit = COREFERENCE_CUES.some((cue) => textIncludes(input.query, cue));
+        const topicalDriftHit = this.detectTopicalDrift(input.query, input.recentTurns);
+        const reasons = [];
+        if (coReferenceHit)
+            reasons.push('coreference_cue');
+        if (topicalDriftHit)
+            reasons.push('topical_drift');
+        if (coverage < this.config.coverageThreshold)
+            reasons.push('coverage_below_threshold');
+        if (topConfidence < this.config.topConfidenceThreshold)
+            reasons.push('top_confidence_below_threshold');
+        const sufficient = reasons.length === 0;
+        return {
+            sufficient,
+            reason: sufficient ? 'layer1_sufficient' : reasons.join('+'),
+            signals: {
+                coverage,
+                topConfidence,
+                coReferenceHit,
+                topicalDriftHit
+            },
+            suggestedFollowupQueries: sufficient
+                ? []
+                : this.buildFollowups(input, missing, compiled.relativeReferences)
+        };
+    }
+    calculateTopConfidence(result) {
+        const facts = [...result.compiledMemory.facts]
+            .sort((a, b) => b.confidence - a.confidence)
+            .slice(0, 3);
+        if (facts.length === 0)
+            return 0;
+        return Math.min(1, Math.max(0, facts.reduce((sum, fact) => sum + fact.confidence, 0) / 3));
+    }
+    detectTopicalDrift(query, recentTurns) {
+        if (!hasTemporalRelative(query))
+            return false;
+        const driftContext = this.buildDriftContext(query, recentTurns);
+        if (!driftContext.trim())
+            return true;
+        return trigramJaccard(query, driftContext) < 0.1;
+    }
+    buildDriftContext(query, turns) {
+        const scored = turns
+            .map((turn, index) => ({
+            turn,
+            index,
+            score: turnRelevanceScore(query, turn.content),
+        }))
+            .filter((item) => item.turn.content.trim().length > 0);
+        const relevant = scored
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score || b.turn.timestamp - a.turn.timestamp || b.index - a.index);
+        const fallback = scored
+            .sort((a, b) => b.turn.timestamp - a.turn.timestamp || b.index - a.index);
+        const candidates = relevant.length > 0 ? relevant : fallback;
+        const selected = [];
+        let usedChars = 0;
+        for (const item of candidates) {
+            const content = item.turn.content.trim();
+            const nextCost = content.length + 1;
+            if (selected.length > 0 && usedChars + nextCost > DRIFT_CONTEXT_CHAR_BUDGET)
+                continue;
+            selected.push(content);
+            usedChars += nextCost;
+            if (usedChars >= DRIFT_CONTEXT_CHAR_BUDGET)
+                break;
+        }
+        return selected.join('\n');
+    }
+    buildFollowups(input, missing, relativeReferences) {
+        const projectHint = input.projectId ? `project:${input.projectId}` : '';
+        const suggestions = [];
+        for (const item of missing)
+            suggestions.push([item, projectHint].filter(Boolean).join(' '));
+        const lastUser = [...input.recentTurns].reverse().find((turn) => turn.role === 'user');
+        const nounPhrase = extractCorePhrase(lastUser?.content || input.query);
+        if (nounPhrase)
+            suggestions.push(`${nounPhrase} ${input.query}`.trim());
+        for (const ref of relativeReferences)
+            suggestions.push([ref, projectHint].filter(Boolean).join(' '));
+        return Array.from(new Set(suggestions.map((item) => item.trim()).filter(Boolean)))
+            .slice(0, this.config.maxSuggestedFollowups);
+    }
+    collectEvidenceText(result) {
+        const parts = [
+            ...result.compiledMemory.facts.flatMap((fact) => [
+                fact.subject,
+                fact.predicateFamily,
+                fact.predicateValue || '',
+                fact.object || '',
+                fact.sourceText
+            ]),
+            ...result.compiledMemory.entityTimeline.flatMap((item) => [
+                item.canonicalName,
+                item.type,
+            ]),
+            ...result.rawEvidence.map((neuron) => neuron.content),
+            ...(result.summaries || []).map((summary) => summary.text)
+        ];
+        return parts.join('\n').toLowerCase();
+    }
+}
+function textIncludes(text, needle) {
+    return text.toLowerCase().includes(needle.toLowerCase());
+}
+function hasTemporalRelative(query) {
+    return TEMPORAL_RELATIVE_CUES.some((cue) => textIncludes(query, cue));
+}
+function trigrams(text) {
+    const normalized = text.toLowerCase().replace(/\s+/g, ' ').trim();
+    if (normalized.length < 3)
+        return new Set(normalized ? [normalized] : []);
+    const grams = new Set();
+    for (let i = 0; i <= normalized.length - 3; i++)
+        grams.add(normalized.slice(i, i + 3));
+    return grams;
+}
+function trigramJaccard(a, b) {
+    const left = trigrams(a);
+    const right = trigrams(b);
+    if (left.size === 0 && right.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const item of left)
+        if (right.has(item))
+            intersection += 1;
+    return intersection / (left.size + right.size - intersection);
+}
+function extractCorePhrase(text) {
+    const tokens = text
+        .replace(/[^\p{L}\p{N}_\-\u4e00-\u9fa5\s]/gu, ' ')
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 2 && !COREFERENCE_CUES.includes(token.toLowerCase()));
+    return tokens.slice(0, 4).join(' ');
+}
+function turnRelevanceScore(query, content) {
+    const queryTokens = tokenizeForRecallGate(query);
+    if (queryTokens.length === 0)
+        return 0;
+    const normalizedContent = content.toLowerCase();
+    const lexicalHits = queryTokens.filter((token) => normalizedContent.includes(token)).length;
+    return lexicalHits / queryTokens.length + trigramJaccard(query, content);
+}
+function tokenizeForRecallGate(text) {
+    return Array.from(new Set(text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}_\-\u4e00-\u9fa5\s]/gu, ' ')
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 2 && !TEMPORAL_RELATIVE_CUES.includes(token))));
+}