cogmem 3.6.2

package/dist/recall/SourceContextMetadata.d.ts

@@ -0,0 +1,49 @@
+import type { MemoryEvent } from '../types/index.js';
+export interface MemoryEventCharRange {
+    start: number;
+    end: number;
+}
+export interface MemoryEventSourceRange {
+    sourceOffset?: number;
+    lineStart?: number;
+    lineEnd?: number;
+    charStart?: number;
+    charEnd?: number;
+}
+export interface SourceContextWindowSide {
+    requestedCount: number;
+    count: number;
+    excludesAnchor: true;
+    roleFilter: 'all';
+    ordering: 'chronological';
+    unit: 'raw_event';
+    eventIds: string[];
+    labels: string[];
+    overlapEventIds: string[];
+}
+export interface SourceContextWindowMetadata {
+    anchorEventId: string;
+    anchorLabel: string;
+    excludesAnchor: true;
+    roleFilter: 'all';
+    ordering: 'chronological';
+    unit: 'raw_event';
+    overlapHandling: 'drop_from_after';
+    overlapEventIds: string[];
+    droppedOverlapEventIds: string[];
+    before: SourceContextWindowSide;
+    after: SourceContextWindowSide;
+}
+export interface NormalizedSourceContextWindow<TEvent extends MemoryEvent = MemoryEvent> {
+    before: TEvent[];
+    after: TEvent[];
+    window: SourceContextWindowMetadata;
+}
+export declare function memoryEventLabel(event: MemoryEvent): string;
+export declare function memoryEventCharRange(event: MemoryEvent): MemoryEventCharRange | undefined;
+export declare function memoryEventSourceRange(event: MemoryEvent): MemoryEventSourceRange | undefined;
+export declare function normalizeSourceContextWindow<TEvent extends MemoryEvent>(anchor: TEvent, before: TEvent[], after: TEvent[], requested: {
+    before: number;
+    after: number;
+}): NormalizedSourceContextWindow<TEvent>;
+//# sourceMappingURL=SourceContextMetadata.d.ts.map

package/dist/recall/SourceContextMetadata.js

@@ -0,0 +1,134 @@
+export function memoryEventLabel(event) {
+    const metadata = eventMetadata(event);
+    const sourceRef = isRecord(metadata.sourceRef) ? metadata.sourceRef : undefined;
+    const metadataLabel = firstLabel([
+        metadata.messageId,
+        metadata.message_id,
+        metadata.telegramMessageId,
+        metadata.telegram_message_id,
+        metadata.openclawMessageId,
+        metadata.openclaw_message_id,
+        metadata.hermesStateDbMessageId,
+        metadata.hermes_state_db_message_id,
+        metadata.sourceMessageId,
+        metadata.source_message_id,
+        metadata.originalMessageId,
+        metadata.original_message_id,
+        sourceRef?.messageId,
+        sourceRef?.message_id,
+        sourceRef?.telegramMessageId,
+        sourceRef?.hermesStateDbMessageId,
+    ]);
+    if (metadataLabel)
+        return metadataLabel;
+    if (Number.isFinite(event.globalSeq))
+        return `#${event.globalSeq}`;
+    const sourceOffset = numberField(event.sourceOffset) ?? numberField(metadata.sourceOffset) ?? numberField(sourceRef?.sourceOffset);
+    if (sourceOffset !== undefined)
+        return `#${sourceOffset}`;
+    return `#${event.eventId.slice(4, 12)}`;
+}
+export function memoryEventCharRange(event) {
+    const metadata = eventMetadata(event);
+    const sourceRef = isRecord(metadata.sourceRef) ? metadata.sourceRef : undefined;
+    const start = numberField(event.charStart) ?? numberField(metadata.charStart) ?? numberField(sourceRef?.charStart);
+    const end = numberField(event.charEnd) ?? numberField(metadata.charEnd) ?? numberField(sourceRef?.charEnd);
+    if (start === undefined || end === undefined)
+        return undefined;
+    return { start, end };
+}
+export function memoryEventSourceRange(event) {
+    const metadata = eventMetadata(event);
+    const sourceRef = isRecord(metadata.sourceRef) ? metadata.sourceRef : undefined;
+    const range = {
+        sourceOffset: numberField(event.sourceOffset) ?? numberField(metadata.sourceOffset) ?? numberField(sourceRef?.sourceOffset),
+        lineStart: numberField(event.lineStart) ?? numberField(metadata.lineStart) ?? numberField(sourceRef?.lineStart),
+        lineEnd: numberField(event.lineEnd) ?? numberField(metadata.lineEnd) ?? numberField(sourceRef?.lineEnd),
+        charStart: numberField(event.charStart) ?? numberField(metadata.charStart) ?? numberField(sourceRef?.charStart),
+        charEnd: numberField(event.charEnd) ?? numberField(metadata.charEnd) ?? numberField(sourceRef?.charEnd),
+    };
+    return Object.values(range).some((value) => value !== undefined) ? range : undefined;
+}
+export function normalizeSourceContextWindow(anchor, before, after, requested) {
+    const seen = new Set([anchor.eventId]);
+    const droppedOverlapEventIds = [];
+    const normalizedBefore = [];
+    for (const event of before) {
+        if (seen.has(event.eventId)) {
+            droppedOverlapEventIds.push(event.eventId);
+            continue;
+        }
+        seen.add(event.eventId);
+        normalizedBefore.push(event);
+    }
+    const normalizedAfter = [];
+    for (const event of after) {
+        if (seen.has(event.eventId)) {
+            droppedOverlapEventIds.push(event.eventId);
+            continue;
+        }
+        seen.add(event.eventId);
+        normalizedAfter.push(event);
+    }
+    const beforeIds = new Set(normalizedBefore.map((event) => event.eventId));
+    const overlapEventIds = unique(normalizedAfter
+        .filter((event) => beforeIds.has(event.eventId))
+        .map((event) => event.eventId));
+    const window = {
+        anchorEventId: anchor.eventId,
+        anchorLabel: memoryEventLabel(anchor),
+        excludesAnchor: true,
+        roleFilter: 'all',
+        ordering: 'chronological',
+        unit: 'raw_event',
+        overlapHandling: 'drop_from_after',
+        overlapEventIds,
+        droppedOverlapEventIds: unique(droppedOverlapEventIds),
+        before: windowSide(requested.before, normalizedBefore, overlapEventIds),
+        after: windowSide(requested.after, normalizedAfter, overlapEventIds),
+    };
+    return {
+        before: normalizedBefore,
+        after: normalizedAfter,
+        window,
+    };
+}
+function windowSide(requestedCount, events, overlapEventIds) {
+    return {
+        requestedCount,
+        count: events.length,
+        excludesAnchor: true,
+        roleFilter: 'all',
+        ordering: 'chronological',
+        unit: 'raw_event',
+        eventIds: events.map((event) => event.eventId),
+        labels: events.map(memoryEventLabel),
+        overlapEventIds,
+    };
+}
+function eventMetadata(event) {
+    const payload = event.payload;
+    return isRecord(payload.metadata) ? payload.metadata : {};
+}
+function firstLabel(values) {
+    for (const value of values) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return `#${value}`;
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed)
+            continue;
+        return trimmed.startsWith('#') ? trimmed : `#${trimmed}`;
+    }
+    return undefined;
+}
+function numberField(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function unique(values) {
+    return Array.from(new Set(values));
+}

package/dist/recall/TopicClassifier.d.ts

@@ -0,0 +1,33 @@
+import type { MemoryGraph } from '../core/MemoryGraph.js';
+import type { Embedder } from '../store/Embedder.js';
+import type { TopicRegistry } from './TopicRegistry.js';
+export interface TopicClassifierOptions {
+    confidenceThreshold?: number;
+    embeddingThreshold?: number;
+    enableEmbedding?: boolean;
+    maxTopicsToScore?: number;
+}
+export interface TopicClassificationResult {
+    topicPath?: string;
+    confidence: number;
+    strategy: 'lexical' | 'embedding' | 'fallback';
+}
+export declare class TopicClassifier {
+    private readonly memoryGraph;
+    private readonly options;
+    private readonly topicRegistry?;
+    private readonly embedder?;
+    private readonly router;
+    constructor(memoryGraph: MemoryGraph, options?: TopicClassifierOptions, topicRegistry?: TopicRegistry | undefined, embedder?: Embedder | undefined);
+    classify(content: string, projectId?: string): TopicClassificationResult;
+    classifyAsync(content: string, projectId?: string): Promise<TopicClassificationResult>;
+    private classifyLexical;
+    private classifyByEmbedding;
+    private scoreTopicVector;
+    private getRepresentativeNeurons;
+    private cosineSimilarity;
+    private getTopicPaths;
+    private matchChineseTopic;
+    private fallback;
+}
+//# sourceMappingURL=TopicClassifier.d.ts.map

package/dist/recall/TopicClassifier.js

@@ -0,0 +1,138 @@
+import { HierarchicalRecallRouter, normalizeTopicPath } from './HierarchicalRecallRouter.js';
+import { ZH_TOPIC_LEXICON } from '../lexicon/zh/index.js';
+export class TopicClassifier {
+    memoryGraph;
+    options;
+    topicRegistry;
+    embedder;
+    router;
+    constructor(memoryGraph, options = {}, topicRegistry, embedder) {
+        this.memoryGraph = memoryGraph;
+        this.options = options;
+        this.topicRegistry = topicRegistry;
+        this.embedder = embedder;
+        this.router = new HierarchicalRecallRouter(memoryGraph);
+    }
+    classify(content, projectId) {
+        return this.classifyLexical(content, projectId);
+    }
+    async classifyAsync(content, projectId) {
+        const lexical = this.classifyLexical(content, projectId);
+        if (lexical.strategy === 'lexical')
+            return lexical;
+        if (this.options.enableEmbedding !== true || !this.embedder || !content.trim())
+            return lexical;
+        const embedding = await this.classifyByEmbedding(content, projectId);
+        return embedding ?? lexical;
+    }
+    classifyLexical(content, projectId) {
+        if (!content.trim()) {
+            return this.fallback();
+        }
+        const zhTopic = this.matchChineseTopic(content);
+        if (zhTopic)
+            return zhTopic;
+        const topics = this.getTopicPaths(projectId)
+            .map((path) => normalizeTopicPath(path))
+            .filter((path) => Boolean(path));
+        if (topics.length === 0) {
+            return this.fallback();
+        }
+        const maxTopicsToScore = Math.max(1, this.options.maxTopicsToScore ?? 50);
+        const scored = this.router.scoreTopics(content, topics.slice(0, maxTopicsToScore));
+        const best = scored[0];
+        const confidenceThreshold = this.options.confidenceThreshold ?? 0.25;
+        if (best && best.score >= confidenceThreshold) {
+            return {
+                topicPath: best.path,
+                confidence: best.score,
+                strategy: 'lexical'
+            };
+        }
+        return this.fallback(best?.score ?? 0);
+    }
+    async classifyByEmbedding(content, projectId) {
+        const queryVector = await this.embedder.embed(content);
+        if (queryVector.length === 0)
+            return null;
+        const threshold = this.options.embeddingThreshold ?? 0.75;
+        const topics = this.getTopicPaths(projectId)
+            .map((path) => normalizeTopicPath(path))
+            .filter((path) => Boolean(path))
+            .slice(0, Math.max(1, this.options.maxTopicsToScore ?? 50));
+        let best = null;
+        for (const topicPath of topics) {
+            const score = this.scoreTopicVector(queryVector, topicPath, projectId);
+            if (!best || score > best.confidence) {
+                best = { topicPath, confidence: score, strategy: 'embedding' };
+            }
+        }
+        return best && best.confidence >= threshold ? best : null;
+    }
+    scoreTopicVector(queryVector, topicPath, projectId) {
+        const representatives = this.getRepresentativeNeurons(topicPath, projectId);
+        if (representatives.length === 0)
+            return 0;
+        return Math.max(...representatives.map((neuron) => this.cosineSimilarity(queryVector, neuron.coordinates.V)));
+    }
+    getRepresentativeNeurons(topicPath, projectId) {
+        const neurons = this.memoryGraph.getNeuronIdsByTopicPrefix(topicPath, projectId)
+            .map((id) => this.memoryGraph.getNeuron(id))
+            .filter((neuron) => Boolean(neuron))
+            .filter((neuron) => neuron.coordinates.V.length > 0);
+        const summary = neurons.find((neuron) => neuron.metadata.tags?.includes('topic_summary') === true);
+        const recent = neurons
+            .filter((neuron) => neuron.id !== summary?.id)
+            .sort((a, b) => (b.metadata.createdAt - a.metadata.createdAt) || a.id.localeCompare(b.id))
+            .slice(0, 3);
+        return summary ? [summary, ...recent] : recent;
+    }
+    cosineSimilarity(a, b) {
+        if (a.length === 0 || b.length === 0)
+            return 0;
+        const length = Math.min(a.length, b.length);
+        let dot = 0;
+        let magnitudeA = 0;
+        let magnitudeB = 0;
+        for (let index = 0; index < length; index++) {
+            dot += a[index] * b[index];
+            magnitudeA += a[index] * a[index];
+            magnitudeB += b[index] * b[index];
+        }
+        if (magnitudeA === 0 || magnitudeB === 0)
+            return 0;
+        return dot / (Math.sqrt(magnitudeA) * Math.sqrt(magnitudeB));
+    }
+    getTopicPaths(projectId) {
+        return this.topicRegistry?.getTopicPaths(projectId) ?? this.memoryGraph.getTopicPaths(projectId);
+    }
+    matchChineseTopic(content) {
+        if (!/[\u3400-\u9fff]/.test(content))
+            return null;
+        let best = null;
+        for (const entry of ZH_TOPIC_LEXICON) {
+            const matched = entry.keywords.filter((keyword) => content.includes(keyword)).length;
+            if (matched === 0)
+                continue;
+            if (!best
+                || matched > best.matched
+                || (matched === best.matched && entry.keywords.length < best.total)) {
+                best = { topicPath: entry.topicPath, matched, total: entry.keywords.length };
+            }
+        }
+        if (!best)
+            return null;
+        return {
+            topicPath: best.topicPath,
+            confidence: Math.min(1, Math.max(0.5, best.matched / Math.min(5, best.total))),
+            strategy: 'lexical',
+        };
+    }
+    fallback(confidence = 0) {
+        return {
+            topicPath: undefined,
+            confidence,
+            strategy: 'fallback'
+        };
+    }
+}

package/dist/recall/TopicDecayPolicy.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryGraph } from '../core/MemoryGraph.js';
+export interface TopicDecayPolicyOptions {
+    staleThresholdDays?: number;
+    minNeuronCount?: number;
+    decayImportanceLevel?: 'low' | 'normal';
+}
+export declare class TopicDecayPolicy {
+    private readonly memoryGraph;
+    private readonly options;
+    constructor(memoryGraph: MemoryGraph, options?: TopicDecayPolicyOptions);
+    findStalePaths(projectId?: string): string[];
+    applyDecay(projectId?: string): number;
+    private getSourceNeurons;
+}
+//# sourceMappingURL=TopicDecayPolicy.d.ts.map

package/dist/recall/TopicDecayPolicy.js

@@ -0,0 +1,46 @@
+import { normalizeTopicPath } from './HierarchicalRecallRouter.js';
+const SUMMARY_TAG = 'topic_summary';
+const DAY_MS = 24 * 60 * 60 * 1000;
+export class TopicDecayPolicy {
+    memoryGraph;
+    options;
+    constructor(memoryGraph, options = {}) {
+        this.memoryGraph = memoryGraph;
+        this.options = options;
+    }
+    findStalePaths(projectId) {
+        const thresholdMs = Math.max(0, this.options.staleThresholdDays ?? 90) * DAY_MS;
+        const minNeuronCount = Math.max(1, this.options.minNeuronCount ?? 5);
+        const cutoff = Date.now() - thresholdMs;
+        return this.memoryGraph.getTopicPaths(projectId)
+            .map((path) => normalizeTopicPath(path))
+            .filter((path) => Boolean(path))
+            .filter((path) => {
+            const neurons = this.getSourceNeurons(path, projectId);
+            if (neurons.length < minNeuronCount)
+                return false;
+            const latestWrite = Math.max(...neurons.map((neuron) => neuron.metadata.createdAt));
+            return latestWrite < cutoff;
+        })
+            .sort();
+    }
+    applyDecay(projectId) {
+        const level = this.options.decayImportanceLevel ?? 'low';
+        let decayed = 0;
+        for (const path of this.findStalePaths(projectId)) {
+            for (const neuron of this.getSourceNeurons(path, projectId)) {
+                if (neuron.metadata.importanceLevel === level)
+                    continue;
+                this.memoryGraph.updateNeuronImportance(neuron.id, level, false);
+                decayed += 1;
+            }
+        }
+        return decayed;
+    }
+    getSourceNeurons(topicPath, projectId) {
+        return this.memoryGraph.getNeuronIdsByTopicPrefix(topicPath, projectId)
+            .map((id) => this.memoryGraph.getNeuron(id))
+            .filter((neuron) => Boolean(neuron))
+            .filter((neuron) => neuron.metadata.tags?.includes(SUMMARY_TAG) !== true);
+    }
+}

package/dist/recall/TopicRegistry.d.ts

@@ -0,0 +1,12 @@
+import type { MemoryGraph } from '../core/MemoryGraph.js';
+export declare class TopicRegistry {
+    private readonly memoryGraph;
+    private readonly cache;
+    constructor(memoryGraph: MemoryGraph);
+    /** Return known topic paths for a project, cached until invalidated. */
+    getTopicPaths(projectId?: string): string[];
+    /** Invalidate topic cache after a write may have changed the topic directory. */
+    invalidate(projectId?: string): void;
+    private cacheKey;
+}
+//# sourceMappingURL=TopicRegistry.d.ts.map

package/dist/recall/TopicRegistry.js

@@ -0,0 +1,26 @@
+const GLOBAL_PROJECT_KEY = '__agent_brain_global__';
+export class TopicRegistry {
+    memoryGraph;
+    cache = new Map();
+    constructor(memoryGraph) {
+        this.memoryGraph = memoryGraph;
+    }
+    /** Return known topic paths for a project, cached until invalidated. */
+    getTopicPaths(projectId) {
+        const key = this.cacheKey(projectId);
+        const cached = this.cache.get(key);
+        if (cached)
+            return [...cached];
+        const paths = this.memoryGraph.getTopicPaths(projectId);
+        this.cache.set(key, [...paths]);
+        return paths;
+    }
+    /** Invalidate topic cache after a write may have changed the topic directory. */
+    invalidate(projectId) {
+        this.cache.delete(this.cacheKey(projectId));
+        this.cache.delete(GLOBAL_PROJECT_KEY);
+    }
+    cacheKey(projectId) {
+        return projectId ?? GLOBAL_PROJECT_KEY;
+    }
+}

package/dist/recall/TopicSummaryBoard.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryGraph } from '../core/MemoryGraph.js';
+import type { SummaryStore } from '../store/SummaryStore.js';
+import type { Neuron } from '../types/index.js';
+export interface TopicSummaryEntry {
+    topicPath: string;
+    projectId: string;
+    summaryNeuronId: string;
+    lastUpdatedAt: number;
+    coveredNeuronCount: number;
+}
+export interface TopicSummaryRefreshOptions {
+    forceRebuild?: boolean;
+}
+export declare class TopicSummaryBoard {
+    private readonly memoryGraph;
+    private readonly summaryStore;
+    constructor(memoryGraph: MemoryGraph, summaryStore: SummaryStore);
+    refresh(topicPath: string, projectId: string, options?: TopicSummaryRefreshOptions): string | null;
+    listEntries(projectId?: string): TopicSummaryEntry[];
+    getSummaryNeuron(topicPath: string, projectId?: string): Neuron | null;
+    private getSourceNeurons;
+    private isSummaryNeuron;
+    private buildSummaryText;
+    private compact;
+    private archiveSummaryWithoutRecallableSources;
+}
+//# sourceMappingURL=TopicSummaryBoard.d.ts.map

package/dist/recall/TopicSummaryBoard.js

@@ -0,0 +1,139 @@
+import { NeuronFactory } from '../core/Neuron.js';
+import { normalizeTopicPath } from './HierarchicalRecallRouter.js';
+import { isRecallableMemoryEvidence } from './RecallGovernance.js';
+const SUMMARY_TAG = 'topic_summary';
+const SUMMARY_SOURCE_TAG = 'topic_summary:auto';
+const SUMMARY_RUN_ID = 'topic_summary_board';
+export class TopicSummaryBoard {
+    memoryGraph;
+    summaryStore;
+    constructor(memoryGraph, summaryStore) {
+        this.memoryGraph = memoryGraph;
+        this.summaryStore = summaryStore;
+    }
+    refresh(topicPath, projectId, options = {}) {
+        const normalized = normalizeTopicPath(topicPath);
+        if (!normalized || !projectId)
+            return null;
+        const existing = this.getSummaryNeuron(normalized, projectId);
+        const sourceNeurons = this.getSourceNeurons(normalized, projectId);
+        if (sourceNeurons.length === 0) {
+            if (existing)
+                this.archiveSummaryWithoutRecallableSources(existing);
+            return null;
+        }
+        const latestSourceAt = Math.max(...sourceNeurons.map((neuron) => neuron.metadata.updatedAt || neuron.metadata.createdAt));
+        if (existing && !options.forceRebuild && (existing.metadata.updatedAt || existing.metadata.createdAt) >= latestSourceAt) {
+            return existing.id;
+        }
+        const now = Date.now();
+        const summaryText = this.buildSummaryText(normalized, sourceNeurons);
+        const tags = [SUMMARY_TAG, SUMMARY_SOURCE_TAG, 'source_filter:recallable', `topic:${normalized}`];
+        const sourceIds = sourceNeurons.map((neuron) => neuron.id);
+        this.summaryStore.insertSummary({
+            projectId,
+            scope: 'project',
+            text: summaryText,
+            confidence: 0.86,
+            status: 'verified',
+            sourceNeuronIds: sourceIds,
+            deepWriteRunId: SUMMARY_RUN_ID,
+            deepWriteCandidateId: normalized,
+            createdAt: now,
+            updatedAt: now
+        });
+        if (existing) {
+            this.memoryGraph.updateNeuronContent(existing.id, summaryText);
+            this.memoryGraph.updateNeuronMetadata(existing.id, {
+                tags,
+                updatedAt: now,
+                confidence: 0.86,
+                importanceLevel: 'normal',
+                isPinned: false,
+                status: 'active'
+            });
+            return existing.id;
+        }
+        const summaryNeuron = NeuronFactory.create(summaryText, this.memoryGraph.getLatestNeuronSelfHash(projectId) || 'genesis', { T: now, S: [0, 0, 0], V: [] }, {
+            projectId,
+            topicPath: normalized,
+            type: 'doc',
+            createdAt: now,
+            updatedAt: now,
+            tags,
+            status: 'active',
+            confidence: 0.86,
+            importanceLevel: 'normal',
+            isPinned: false,
+            sourceType: 'llm_inference'
+        });
+        this.memoryGraph.addNeuron(summaryNeuron);
+        return summaryNeuron.id;
+    }
+    listEntries(projectId) {
+        return this.memoryGraph.getTopicPaths(projectId)
+            .map((path) => normalizeTopicPath(path))
+            .filter((path) => Boolean(path))
+            .map((topicPath) => {
+            const summary = this.getSummaryNeuron(topicPath, projectId);
+            if (!summary)
+                return null;
+            return {
+                topicPath,
+                projectId: summary.metadata.projectId || '',
+                summaryNeuronId: summary.id,
+                lastUpdatedAt: summary.metadata.updatedAt || summary.metadata.createdAt,
+                coveredNeuronCount: this.getSourceNeurons(topicPath, summary.metadata.projectId).length
+            };
+        })
+            .filter((entry) => Boolean(entry))
+            .sort((a, b) => a.topicPath.localeCompare(b.topicPath));
+    }
+    getSummaryNeuron(topicPath, projectId) {
+        const normalized = normalizeTopicPath(topicPath);
+        if (!normalized)
+            return null;
+        const candidates = this.memoryGraph.getNeuronIdsByTopicPrefix(normalized, projectId)
+            .map((id) => this.memoryGraph.getNeuron(id))
+            .filter((neuron) => Boolean(neuron))
+            .filter((neuron) => neuron.metadata.topicPath === normalized
+            && neuron.metadata.type === 'doc'
+            && (neuron.metadata.status ?? 'active') !== 'archived'
+            && this.isSummaryNeuron(neuron));
+        candidates.sort((a, b) => (b.metadata.updatedAt || b.metadata.createdAt) - (a.metadata.updatedAt || a.metadata.createdAt));
+        return candidates[0] || null;
+    }
+    getSourceNeurons(topicPath, projectId) {
+        return this.memoryGraph.getNeuronIdsByTopicPrefix(topicPath, projectId)
+            .map((id) => this.memoryGraph.getNeuron(id))
+            .filter((neuron) => Boolean(neuron))
+            .filter((neuron) => !this.isSummaryNeuron(neuron))
+            .filter((neuron) => isRecallableMemoryEvidence(neuron))
+            .sort((a, b) => (b.metadata.updatedAt || b.metadata.createdAt) - (a.metadata.updatedAt || a.metadata.createdAt));
+    }
+    isSummaryNeuron(neuron) {
+        return neuron.metadata.tags?.includes(SUMMARY_TAG) === true;
+    }
+    buildSummaryText(topicPath, sourceNeurons) {
+        const samples = sourceNeurons
+            .slice(0, 5)
+            .map((neuron) => this.compact(neuron.content))
+            .filter(Boolean);
+        return [
+            `Topic summary for ${topicPath}.`,
+            `Covers ${sourceNeurons.length} memories.`,
+            ...samples.map((sample) => `- ${sample}`)
+        ].join('\n');
+    }
+    compact(content) {
+        return content.replace(/\s+/g, ' ').trim().slice(0, 180);
+    }
+    archiveSummaryWithoutRecallableSources(summary) {
+        const tags = summary.metadata.tags || [];
+        this.memoryGraph.updateNeuronMetadata(summary.id, {
+            status: 'archived',
+            updatedAt: Date.now(),
+            tags: Array.from(new Set([...tags, 'governance:no_recallable_topic_sources']))
+        });
+    }
+}

package/dist/recall/VectorCandidateFilter.d.ts

@@ -0,0 +1,50 @@
+import type { MemoryGraph } from '../core/MemoryGraph.js';
+import type { Neuron } from '../types/index.js';
+export interface VectorFilterContext {
+    projectId?: string;
+    topicPath?: string;
+    queryTime: number;
+    maxStaleMs?: number;
+    entityHints?: string[];
+}
+export interface VectorFilterRule {
+    name: string;
+    filter(neuronIds: string[], context: VectorFilterContext): string[];
+}
+export declare class VectorCandidateFilter {
+    private readonly rules;
+    constructor(rules?: VectorFilterRule[]);
+    filter(neuronIds: string[], ctx: VectorFilterContext): string[];
+}
+declare abstract class MemoryGraphVectorFilterRule implements VectorFilterRule {
+    protected readonly memoryGraph: MemoryGraph;
+    abstract readonly name: string;
+    abstract filter(neuronIds: string[], context: VectorFilterContext): string[];
+    constructor(memoryGraph: MemoryGraph);
+    protected neuron(id: string): Neuron | null;
+}
+export declare class WorkspaceFilter extends MemoryGraphVectorFilterRule {
+    readonly name = "workspace";
+    filter(neuronIds: string[], context: VectorFilterContext): string[];
+}
+export declare class TopicFilter extends MemoryGraphVectorFilterRule {
+    readonly name = "topic";
+    filter(neuronIds: string[], context: VectorFilterContext): string[];
+}
+export declare class StaleFilter extends MemoryGraphVectorFilterRule {
+    readonly name = "stale";
+    filter(neuronIds: string[], context: VectorFilterContext): string[];
+}
+export declare class StatusFilter extends MemoryGraphVectorFilterRule {
+    readonly name = "status";
+    filter(neuronIds: string[], _context: VectorFilterContext): string[];
+}
+export declare class CredibilityFilter extends MemoryGraphVectorFilterRule {
+    private readonly threshold;
+    readonly name = "credibility";
+    constructor(memoryGraph: MemoryGraph, threshold?: number);
+    filter(neuronIds: string[], _context: VectorFilterContext): string[];
+}
+export declare function createDefaultVectorCandidateFilter(memoryGraph: MemoryGraph): VectorCandidateFilter;
+export {};
+//# sourceMappingURL=VectorCandidateFilter.d.ts.map