cogmem 3.6.5 → 3.7.1

package/dist/atlas/MemoryAtlasService.d.ts

@@ -1,9 +1,10 @@
 import type { EventStore } from '../store/EventStore.js';
-import type { MemoryAtlasStore } from '../store/MemoryAtlasStore.js';
+import { type MemoryAtlasStore } from '../store/MemoryAtlasStore.js';
 import type { MemoryAtlasNodeDetail, MemoryAtlasPathResult, MemoryAtlasQueryOptions, MemoryAtlasSlice, MemoryAtlasTimelineResult } from './MemoryAtlasTypes.js';
 export declare class MemoryAtlasService {
     private store;
     private eventStore;
+    private readonly facetPlanner;
     constructor(store: MemoryAtlasStore, eventStore: EventStore);
     overview(options: MemoryAtlasQueryOptions): MemoryAtlasSlice;
     search(query: string, options: MemoryAtlasQueryOptions): MemoryAtlasSlice;
@@ -16,7 +17,9 @@ export declare class MemoryAtlasService {
         maxHops?: number;
     }): MemoryAtlasPathResult;
     timeline(query: string, options: MemoryAtlasQueryOptions): MemoryAtlasTimelineResult;
+    private searchFacetCardsWithRelaxation;
     private attachEvidence;
+    private attachCardEvidence;
     private evidence;
     private edgesFor;
     private safeEdges;

package/dist/atlas/MemoryAtlasService.js

@@ -1,8 +1,11 @@
+import { MEMORY_ATLAS_PROJECTION_NAME } from '../store/MemoryAtlasStore.js';
 import { eventTextForMemory } from '../episode/CogmemBlockStripper.js';
+import { FacetQueryPlanner } from './FacetQueryPlanner.js';
 import { compileAtlasQuery } from './MemoryAtlasQueryCompiler.js';
 export class MemoryAtlasService {
     store;
     eventStore;
+    facetPlanner = new FacetQueryPlanner();
     constructor(store, eventStore) {
         this.store = store;
         this.eventStore = eventStore;
@@ -14,13 +17,29 @@ export class MemoryAtlasService {
     }
     search(query, options) {
         const projectId = requiredProject(options.projectId);
-        const nodes = this.store.search(boundedQuery(query), projectId, boundedLimit(options.limit));
+        const limit = boundedLimit(options.limit);
+        const facetResult = this.searchFacetCardsWithRelaxation(query, projectId, limit, options);
+        const cards = facetResult.cards;
+        let nodes = this.store.search(boundedQuery(query), projectId, limit);
+        if (cards.length) {
+            const cardNodes = cards.map((card) => this.store.getNode(card.canonicalId, projectId)).filter((node) => Boolean(node));
+            nodes = uniqueNodes([...cardNodes, ...nodes]).slice(0, limit);
+        }
         const withEvidence = this.attachEvidence(nodes, projectId, options);
-        return slice(projectId, withEvidence, this.edgesFor(withEvidence, projectId), query);
+        const result = slice(projectId, withEvidence, this.edgesFor(withEvidence, projectId), query);
+        result.facets = facetsForPlan(facetResult.plan);
+        result.matchedFacets = cards.flatMap((card) => card.matchedFacets);
+        if (cards.length)
+            result.cards = this.attachCardEvidence(cards, projectId, options);
+        if (facetResult.relaxationTrace.length)
+            result.relaxationTrace = facetResult.relaxationTrace;
+        return result;
     }
     explore(query, options) {
         const projectId = requiredProject(options.projectId);
         const limit = boundedLimit(options.limit);
+        const facetResult = this.searchFacetCardsWithRelaxation(query, projectId, limit, options);
+        const cards = facetResult.cards;
         const compiled = compileAtlasQuery(boundedQuery(query), options.now);
         const target = this.store.resolveTargetNodeIds(projectId, compiled.text);
         let nodes = this.store.searchFaceted(query, projectId, limit, {
@@ -28,6 +47,10 @@ export class MemoryAtlasService {
             keywords: target.nodeIds.length ? compiled.keywords : compiled.tokens,
             targetNodeIds: target.nodeIds.length ? target.nodeIds : undefined,
         });
+        if (cards.length) {
+            const cardNodes = cards.map((card) => this.store.getNode(card.canonicalId, projectId)).filter((node) => Boolean(node));
+            nodes = uniqueNodes([...cardNodes, ...nodes]).slice(0, limit);
+        }
         if (compiled.actionIntent) {
             const actions = this.store.listActions(projectId, { target: compiled.target, targetEntityIds: target.entitySourceIds,
                 from: compiled.range?.from, to: compiled.range?.to, limit });
@@ -36,7 +59,15 @@ export class MemoryAtlasService {
         const nodesWithEvidence = this.attachEvidence(nodes, projectId, options);
         const edges = this.edgesFor(nodesWithEvidence, projectId);
         const result = slice(projectId, nodesWithEvidence, edges, query);
-        result.facets = { time: compiled.range, target: target.labels.join(', ') || compiled.target, memoryKinds: compiled.memoryKinds, keywords: compiled.keywords };
+        result.facets = {
+            ...facetsForPlan(facetResult.plan),
+            legacy: { time: compiled.range, target: target.labels.join(', ') || compiled.target, memoryKinds: compiled.memoryKinds, keywords: compiled.keywords },
+        };
+        result.matchedFacets = cards.flatMap((card) => card.matchedFacets);
+        if (cards.length)
+            result.cards = this.attachCardEvidence(cards, projectId, options);
+        if (facetResult.relaxationTrace.length)
+            result.relaxationTrace = facetResult.relaxationTrace;
         const hasFacet = Boolean(compiled.range || compiled.target || compiled.memoryKinds.length || compiled.tokens.length);
         result.coldMemoryResurrected = hasFacet && nodes.some((node) => node.activation <= 0.1);
         return result;
@@ -57,7 +88,8 @@ export class MemoryAtlasService {
         if (!Number.isInteger(hops) || hops < 1 || hops > 2)
             throw new Error('hops must be between 1 and 2');
         const limit = boundedLimit(options.limit);
-        const seen = new Set([boundedId(nodeId)]);
+        const start = canonicalInputNodeId(this.store, boundedId(nodeId), projectId);
+        const seen = new Set([start]);
         let frontier = [...seen];
         const selectedEdges = [];
         for (let depth = 0; depth < hops; depth += 1) {
@@ -80,8 +112,8 @@ export class MemoryAtlasService {
     path(from, to, options) {
         const projectId = requiredProject(options.projectId);
         const maxHops = Math.max(1, Math.min(options.maxHops ?? 6, 6));
-        const start = boundedId(from);
-        const target = boundedId(to);
+        const start = canonicalInputNodeId(this.store, boundedId(from), projectId);
+        const target = canonicalInputNodeId(this.store, boundedId(to), projectId);
         const parents = new Map();
         const best = new Map([[start, 0]]);
         const queue = [{ id: start, cost: 0, hops: 0 }];
@@ -134,19 +166,22 @@ export class MemoryAtlasService {
             pathEdges.reverse();
         }
         const path = found ? pathIds.map((id) => this.store.getNode(id, projectId)).filter((node) => Boolean(node)) : [];
-        return { version: 'memory_atlas.v1', projectId, from: start, to: target, path,
+        return { version: MEMORY_ATLAS_PROJECTION_NAME, projectId, from: start, to: target, path,
             edges: found ? this.safeEdges(pathEdges, projectId) : [], truncated: expanded.size >= 2000 };
     }
     timeline(query, options) {
         const projectId = requiredProject(options.projectId);
         const compiled = compileAtlasQuery(boundedQuery(query), options.now);
         const limit = boundedLimit(options.limit);
+        const facetResult = this.searchFacetCardsWithRelaxation(query, projectId, limit, options);
+        const cards = this.attachCardEvidence(facetResult.cards, projectId, options)
+            .sort((left, right) => dateKey(left) - dateKey(right) || left.displayTitle.localeCompare(right.displayTitle));
         const target = this.store.resolveTargetNodeIds(projectId, compiled.text);
         const nodes = this.store.searchFaceted(query, projectId, limit, {
             from: compiled.range?.from, to: compiled.range?.to, memoryKinds: compiled.memoryKinds,
             keywords: target.nodeIds.length ? compiled.keywords : compiled.tokens,
             targetNodeIds: target.nodeIds.length ? target.nodeIds : undefined,
-        }).sort((left, right) => Number(right.occurredAt || 0) - Number(left.occurredAt || 0)).map((node) => {
+        }).sort((left, right) => Number(left.occurredAt || 0) - Number(right.occurredAt || 0)).map((node) => {
             const evidence = this.evidence(node.id, projectId, options.evidenceLimit, options.includeEvidence);
             const evidenceTotal = this.store.evidenceTotal(node.id, projectId);
             return { ...node, evidenceCount: evidenceTotal, evidenceTotal, evidenceReturned: evidence.length, evidence, neighbors: [] };
@@ -154,8 +189,28 @@ export class MemoryAtlasService {
         const actions = this.store.listActions(projectId, { target: compiled.target, targetEntityIds: target.entitySourceIds,
             from: compiled.range?.from, to: compiled.range?.to, limit: boundedLimit(options.limit) })
             .map((action) => ({ ...action, evidence: this.evidence(action.id, projectId, options.evidenceLimit, options.includeEvidence) }));
-        return { version: 'memory_atlas.v1', projectId, query, range: compiled.range,
-            temporalResurrection: Boolean(compiled.range && [...nodes, ...actions].length), nodes, actions, warnings: [] };
+        return { version: MEMORY_ATLAS_PROJECTION_NAME, projectId, query, range: compiled.range,
+            temporalResurrection: Boolean((compiled.range || facetResult.plan.temporalIntent) && [...nodes, ...actions, ...cards].length),
+            nodes, actions, cards,
+            groupedByIssue: groupCardsByIssue(cards),
+            relaxationTrace: facetResult.relaxationTrace.length ? facetResult.relaxationTrace : undefined,
+            facets: facetsForPlan(facetResult.plan),
+            matchedFacets: cards.flatMap((card) => card.matchedFacets),
+            warnings: [] };
+    }
+    searchFacetCardsWithRelaxation(query, projectId, limit, options) {
+        let plan = this.facetPlanner.plan(boundedQuery(query), { projectId, now: options.now });
+        const relaxationTrace = [];
+        let cards = plan.facets.length ? this.store.searchCanonicalEpisodeCards(projectId, plan, limit) : [];
+        for (let attempt = 0; !cards.length && plan.facets.length && attempt < 3; attempt += 1) {
+            const relaxed = relaxFacetPlan(plan);
+            if (!relaxed)
+                break;
+            plan = relaxed.plan;
+            cards = this.store.searchCanonicalEpisodeCards(projectId, plan, limit);
+            relaxationTrace.push(...relaxed.trace);
+        }
+        return { plan, cards, relaxationTrace };
     }
     attachEvidence(nodes, projectId, options) {
         return nodes.map((node) => {
@@ -164,6 +219,17 @@ export class MemoryAtlasService {
             return { ...node, evidenceCount: evidenceTotal, evidenceTotal, evidenceReturned: evidence.length, evidence };
         });
     }
+    attachCardEvidence(cards, projectId, options) {
+        return cards.map((card) => {
+            const evidence = this.evidence(card.canonicalId, projectId, options.evidenceLimit, options.includeEvidence);
+            return {
+                ...card,
+                sourceLocator: evidence[0]?.sourceLocator ?? card.sourceLocator,
+                evidenceTotal: Math.max(card.evidenceTotal, this.store.evidenceTotal(card.canonicalId, projectId)),
+                evidenceReturned: evidence.length,
+            };
+        });
+    }
     evidence(nodeId, projectId, requested, includeExcerpt) {
         const limit = Math.max(1, Math.min(requested ?? 2, 10));
         return this.store.evidenceIds(nodeId, projectId, limit).flatMap((eventId) => {
@@ -203,6 +269,17 @@ export class MemoryAtlasService {
             .flatMap((chunk) => this.store.findEdgesFromNodesToTarget(projectId, chunk, target)));
     }
 }
+function canonicalInputNodeId(store, id, projectId) {
+    if (id.startsWith(`entity:${projectId}:`))
+        return id;
+    if (!id.startsWith('entity:'))
+        return id;
+    const entityId = id.slice('entity:'.length);
+    if (!entityId.startsWith('facet:'))
+        return id;
+    const scoped = `entity:${projectId}:${entityId}`;
+    return store.getNode(scoped, projectId) ? scoped : id;
+}
 function requiredProject(value) { if (!value?.trim())
     throw new Error('projectId is required for Memory Atlas queries'); return value.trim(); }
 function boundedLimit(value) { if (value !== undefined && (!Number.isFinite(value) || value < 1))
@@ -229,7 +306,93 @@ function chunked(values, size) {
         chunks.push(values.slice(index, index + size));
     return chunks;
 }
-function slice(projectId, nodes, edges, query) { return { version: 'memory_atlas.v1', projectId, query, nodes, edges, nextActions: nodes.slice(0, 5).map((node) => ({ label: `Inspect ${node.label}`, tool: 'cogmem_graph_node', args: { id: node.id, projectId } })), warnings: [] }; }
+function slice(projectId, nodes, edges, query) { return { version: MEMORY_ATLAS_PROJECTION_NAME, projectId, query, nodes, edges, nextActions: nodes.slice(0, 5).map((node) => ({ label: `Inspect ${node.label}`, tool: 'cogmem_graph_node', args: { id: node.id, projectId } })), warnings: [] }; }
+function facetsForPlan(plan) {
+    return {
+        planner: {
+            intent: plan.intent,
+            operator: plan.operator,
+            temporalIntent: plan.temporalIntent,
+            groupBy: plan.groupBy,
+            exactness: plan.exactness,
+            keywords: plan.keywords,
+            facets: plan.facets.map((facet) => ({
+                type: facet.type,
+                value: facet.value,
+                label: facet.label,
+                nodeId: facet.nodeId || `${facet.type}:${facet.value}`,
+                relation: facet.relation || 'MATCHES',
+            })),
+        },
+    };
+}
+function dateKey(card) {
+    if (card.localDate && /^\d{4}-\d{2}-\d{2}$/u.test(card.localDate)) {
+        return Date.parse(`${card.localDate}T00:00:00.000Z`);
+    }
+    return Number.POSITIVE_INFINITY;
+}
+function groupCardsByIssue(cards) {
+    const groups = new Map();
+    for (const card of cards) {
+        const key = card.issueType || 'unclassified';
+        groups.set(key, [...(groups.get(key) || []), card]);
+    }
+    return Array.from(groups.entries()).map(([issueType, group]) => ({ issueType, cards: group }));
+}
+function relaxFacetPlan(plan) {
+    const dayFacet = plan.facets.find((facet) => facet.type === 'time' && facet.granularity === 'day');
+    if (dayFacet) {
+        const monthValue = dayFacet.value.slice(0, 7);
+        return {
+            plan: replaceFacet(plan, dayFacet, {
+                ...dayFacet,
+                value: monthValue,
+                label: monthValue,
+                nodeId: dayFacet.nodeId?.replace(dayFacet.value, monthValue),
+                relation: 'OCCURRED_IN',
+                granularity: 'month',
+            }),
+            trace: [{ from: dayFacet.value, to: monthValue, reason: 'exact day facet had no canonical episode match; relaxed to parent month' }],
+        };
+    }
+    const monthFacet = plan.facets.find((facet) => facet.type === 'time' && facet.granularity === 'month');
+    if (monthFacet) {
+        const yearValue = monthFacet.value.slice(0, 4);
+        return {
+            plan: replaceFacet(plan, monthFacet, {
+                ...monthFacet,
+                value: yearValue,
+                label: yearValue,
+                nodeId: monthFacet.nodeId?.replace(monthFacet.value, yearValue),
+                relation: 'OCCURRED_IN',
+                granularity: 'year',
+            }),
+            trace: [{ from: monthFacet.value, to: yearValue, reason: 'exact month facet had no canonical episode match; relaxed to parent year' }],
+        };
+    }
+    const issueFacet = plan.facets.find((facet) => facet.type === 'issue');
+    const topicFacet = plan.facets.find((facet) => facet.type === 'topic');
+    if (issueFacet && topicFacet) {
+        return {
+            plan: {
+                ...plan,
+                exactness: 'relaxed',
+                requiresIntersection: plan.facets.length - 1 > 1,
+                facets: plan.facets.filter((facet) => facet !== issueFacet),
+            },
+            trace: [{ from: issueFacet.value, to: topicFacet.value, reason: 'issue facet had no canonical episode match; relaxed to parent topic' }],
+        };
+    }
+    return null;
+}
+function replaceFacet(plan, from, to) {
+    return {
+        ...plan,
+        exactness: 'relaxed',
+        facets: plan.facets.map((facet) => facet === from ? to : facet),
+    };
+}
 function atlasSourceLocator(event, projectId) {
     const project = projectId || event.projectId;
     const projectArg = project ? ` --project ${cliArg(project)}` : '';

package/dist/atlas/MemoryAtlasTypes.d.ts

@@ -1,4 +1,4 @@
-export type MemoryAtlasNodeType = 'project' | 'topic' | 'entity' | 'cluster' | 'episode' | 'belief' | 'action' | 'time' | 'event';
+export type MemoryAtlasNodeType = 'project' | 'topic' | 'issue' | 'entity' | 'session' | 'thread' | 'memoryKind' | 'actionKind' | 'cluster' | 'episode' | 'raw_event' | 'belief' | 'action' | 'time' | 'event' | 'decision' | 'correction';
 export interface MemoryAtlasEvidence {
     eventId: string;
     globalSeq?: number;
@@ -39,6 +39,48 @@ export interface MemoryAtlasNode {
     /** Bounded first-hop raw evidence locators for agent-facing graph search/explore responses. */
     evidence?: MemoryAtlasEvidence[];
 }
+export interface MemoryAtlasMatchedFacet {
+    type: 'time' | 'topic' | 'issue' | 'entity' | 'session' | 'thread' | 'memoryKind' | 'actionKind';
+    value: string;
+    label: string;
+    nodeId: string;
+    relation: string;
+}
+export interface MemoryAtlasMatchedPath {
+    facet: MemoryAtlasMatchedFacet;
+    via: string[];
+    relation: string;
+    confidence: number;
+}
+export interface MemoryAtlasRelatedCard {
+    canonicalId: string;
+    displayTitle: string;
+    reason: string;
+    matchedFacets?: MemoryAtlasMatchedFacet[];
+}
+export interface MemoryAtlasCard {
+    canonicalId: string;
+    nodeType: MemoryAtlasNodeType;
+    displayTitle: string;
+    oneLineSummary?: string;
+    matchedFacets: MemoryAtlasMatchedFacet[];
+    matchedPaths: MemoryAtlasMatchedPath[];
+    parentTopics: string[];
+    issueType?: string;
+    eventKind?: string;
+    localDate?: string;
+    whyMatched: string;
+    relatedButNotSelected: MemoryAtlasRelatedCard[];
+    sourceLocator?: MemoryAtlasEvidence['sourceLocator'];
+    evidenceEventIds: string[];
+    evidenceTotal: number;
+    evidenceReturned: number;
+}
+export interface MemoryAtlasRelaxationStep {
+    from: string;
+    to: string;
+    reason: string;
+}
 export interface MemoryAtlasEdge {
     source: string;
     relation: string;
@@ -52,7 +94,7 @@ export interface MemoryAtlasNextAction {
     args: Record<string, unknown>;
 }
 export interface MemoryAtlasSlice {
-    version: 'memory_atlas.v1';
+    version: 'memory_atlas.v2';
     projectId: string;
     query?: string;
     nodes: MemoryAtlasNode[];
@@ -60,15 +102,29 @@ export interface MemoryAtlasSlice {
     nextActions: MemoryAtlasNextAction[];
     warnings: string[];
     facets?: {
-        time?: {
-            from: number;
-            to: number;
-            label: string;
+        planner?: {
+            intent: string;
+            operator: string;
+            temporalIntent?: string;
+            groupBy?: string;
+            exactness: string;
+            facets: MemoryAtlasMatchedFacet[];
+            keywords: string[];
+        };
+        legacy?: {
+            time?: {
+                from: number;
+                to: number;
+                label: string;
+            };
+            target?: string;
+            memoryKinds: string[];
+            keywords: string[];
         };
-        target?: string;
-        memoryKinds: string[];
-        keywords: string[];
     };
+    matchedFacets?: MemoryAtlasMatchedFacet[];
+    cards?: MemoryAtlasCard[];
+    relaxationTrace?: MemoryAtlasRelaxationStep[];
     coldMemoryResurrected?: boolean;
 }
 export interface MemoryAtlasNodeDetail extends MemoryAtlasNode {
@@ -87,7 +143,7 @@ export interface MemoryAtlasAction {
     evidence: MemoryAtlasEvidence[];
 }
 export interface MemoryAtlasTimelineResult {
-    version: 'memory_atlas.v1';
+    version: 'memory_atlas.v2';
     projectId: string;
     query: string;
     range?: {
@@ -98,10 +154,18 @@ export interface MemoryAtlasTimelineResult {
     temporalResurrection: boolean;
     nodes: MemoryAtlasNodeDetail[];
     actions: MemoryAtlasAction[];
+    cards?: MemoryAtlasCard[];
+    groupedByIssue?: Array<{
+        issueType: string;
+        cards: MemoryAtlasCard[];
+    }>;
+    relaxationTrace?: MemoryAtlasRelaxationStep[];
+    facets?: MemoryAtlasSlice['facets'];
+    matchedFacets?: MemoryAtlasMatchedFacet[];
     warnings: string[];
 }
 export interface MemoryAtlasPathResult {
-    version: 'memory_atlas.v1';
+    version: 'memory_atlas.v2';
     projectId: string;
     from: string;
     to: string;

package/dist/bin/memory.js

@@ -28,6 +28,7 @@ function readArgs(argv) {
         command,
         query: stringArg(values, 'query') || stringArg(values, 'q'),
         eventId: stringArg(values, 'event') || stringArg(values, 'event-id'),
+        episodeId: stringArg(values, 'episode') || stringArg(values, 'episode-id'),
         nodeId: stringArg(values, 'id') || stringArg(values, 'node-id'),
         fromId: stringArg(values, 'from'),
         toId: stringArg(values, 'to'),
@@ -96,6 +97,7 @@ function usage() {
         '  graph-neighbors      expand --id by --hops 1..2',
         '  graph-path           find a bounded path from --from to --to',
         '  graph-timeline       reconstruct entity/time/action history for --query',
+        '  graph-reindex        reproject one Atlas episode/card by --event or --episode without rebuilding the whole graph',
         '',
         'Common options:',
         '  --project <id>       scope to one project',
@@ -122,7 +124,7 @@ function usage() {
         '  --interval-ms <n>    watch sleep interval, default 300000',
         '  --max-runs <n>       stop watch after n iterations; omit for long-running worker',
         '  --agent <id>         agent id for governed recall, default openclaw',
-        '  --intent <intent>    memory_recall, previous_session_summary, forensic_quote, or historical_discussion',
+        '  --intent <intent>    memory_recall, previous_session_summary, forensic_quote, historical_discussion, or action_history',
         '  --db <memory.db>     open an explicit database path',
         '  --config <toml>      open a cogmem TOML config',
         '  --include-evidence   include bounded raw excerpts; event ids are always returned',
@@ -158,7 +160,8 @@ function isMemoryCommand(value) {
         || value === 'graph-node'
         || value === 'graph-neighbors'
         || value === 'graph-path'
-        || value === 'graph-timeline';
+        || value === 'graph-timeline'
+        || value === 'graph-reindex';
 }
 function reviewActionArg(values, key) {
     const raw = stringArg(values, key);
@@ -172,9 +175,9 @@ function recallIntentArg(values, key) {
     const raw = stringArg(values, key);
     if (!raw)
         return undefined;
-    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote' || raw === 'historical_discussion')
+    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote' || raw === 'historical_discussion' || raw === 'action_history')
         return raw;
-    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote, historical_discussion`);
+    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote, historical_discussion, action_history`);
 }
 function orderArg(values, key) {
     const raw = stringArg(values, key);
@@ -573,6 +576,9 @@ function runRecall(kernel, args) {
         decisionTrace: result.decisionTrace,
         strategyCapsule,
         narrative: result.narrative,
+        atlasCards: result.atlasCards,
+        relatedButNotSelected: result.relatedButNotSelected,
+        relaxationTrace: result.relaxationTrace,
         items: result.items,
     };
 }
@@ -600,6 +606,13 @@ function runGraphCommand(kernel, args) {
         evidenceLimit: args.evidenceLimit, now: args.now,
         refresh: args.refresh ? true : (args.staleOk ? false : undefined),
         staleOk: args.staleOk || !args.refresh };
+    if (args.command === 'graph-reindex') {
+        if (!args.eventId && !args.episodeId)
+            throw new Error(`graph-reindex requires --event or --episode.\n${usage()}`);
+        if (args.eventId && args.episodeId)
+            throw new Error(`graph-reindex accepts exactly one of --event or --episode.\n${usage()}`);
+        return kernel.reindexMemoryAtlas({ projectId, eventId: args.eventId, episodeId: args.episodeId });
+    }
     if (args.command === 'graph')
         return kernel.graphOverview(options);
     if (args.command === 'graph-search') {
@@ -881,7 +894,7 @@ function printHuman(command, payload) {
         return;
     }
     if (command === 'graph' || command.startsWith('graph-')) {
-        console.log(`memoryAtlas: ${payload.version || 'memory_atlas.v1'} project=${payload.projectId || 'unknown'}`);
+        console.log(`memoryAtlas: ${payload.version || 'memory_atlas.v2'} project=${payload.projectId || 'unknown'}`);
         const rows = Array.isArray(payload.nodes) ? payload.nodes
             : Array.isArray(payload.path) ? payload.path
                 : Array.isArray(payload.actions) ? payload.actions

package/dist/factory.d.ts

@@ -326,9 +326,15 @@ export type EpisodeRepairInput = {
 };
 export interface EpisodeRepairResult {
     repairId: string;
+    applied: boolean;
     operation: EpisodeRepairInput['operation'];
     affectedEpisodeIds: string[];
+    changedFields: string[];
     staleCandidateIds: string[];
+    requeuedDream: boolean;
+    graphRefreshNeeded: boolean;
+    nextCommands: string[];
+    note: string;
 }
 export interface ToolCallMemoryEventInput {
     projectId?: string;
@@ -635,6 +641,18 @@ export declare class MemoryKernel {
         documents: number;
         actions: number;
     };
+    reindexMemoryAtlas(options: {
+        projectId: string;
+        eventId?: string;
+        episodeId?: string;
+    }): {
+        projectId: string;
+        episodeIds: string[];
+        refreshed: boolean;
+        curatedEpisodes: number;
+        facetEdges: number;
+        reviewNeeded: number;
+    };
     ensureMemoryAtlas(options: {
         projectId: string;
     }): {

package/dist/factory.js

@@ -83,7 +83,7 @@ import { SqliteVecStore } from './store/SqliteVecStore.js';
 import { VectorStore } from './store/VectorStore.js';
 import { config } from './utils/Config.js';
 import { KernelRunningError, SnapshotExporter, SnapshotImporter, } from './snapshot/index.js';
-const CORE_VERSION = '3.6.5';
+const CORE_VERSION = '3.7.1';
 const LATEST_SCHEMA_VERSION = 27;
 export class MemoryKernel {
     options;
@@ -1056,6 +1056,7 @@ export class MemoryKernel {
         const affected = new Set();
         const before = {};
         const previousStatuses = new Map();
+        let requeuedDream = input.operation === 'requeue-dream' || input.operation === 'invalidate-dream-run';
         if (input.operation === 'move-event') {
             const link = this.episodeStore.getEventLink(input.eventId);
             const source = link ? this.episodeStore.getEpisode(link.episodeId) : undefined;
@@ -1169,11 +1170,30 @@ export class MemoryKernel {
             const episode = this.episodeStore.getEpisode(episodeId);
             if (episode?.eventCount && episode.status === 'sealed') {
                 this.episodeStore.requeueDreamForRepair(episodeId, input.operation === 'invalidate-dream-run' ? input.mode || 'normal' : 'normal', now);
+                requeuedDream = true;
             }
         }
         const after = Object.fromEntries([...affected].map((episodeId) => [episodeId, this.episodeStore.getEpisode(episodeId)]));
         const repairId = this.episodeStore.recordRepairAudit({ projectId: input.projectId, operation: input.operation, payload: input, before, after, now });
-        return { repairId, operation: input.operation, affectedEpisodeIds: [...affected], staleCandidateIds };
+        const affectedEpisodeIds = [...affected];
+        const nextCommands = affectedEpisodeIds.length
+            ? affectedEpisodeIds.map((episodeId) => `cogmem memory graph-reindex --project ${input.projectId} --episode ${episodeId} --json`)
+            : [];
+        return {
+            repairId,
+            applied: true,
+            operation: input.operation,
+            affectedEpisodeIds,
+            changedFields: changedFieldsForRepair(input),
+            staleCandidateIds,
+            requeuedDream,
+            graphRefreshNeeded: affectedEpisodeIds.length > 0,
+            nextCommands: [
+                ...nextCommands,
+                `cogmem memory graph-explore --project ${input.projectId} --query "<query>" --json`,
+            ],
+            note: 'repairId is an audit id, not a dream candidate id; do not run memory dream --promote just because repairId exists.',
+        };
     }
     listDreamCandidates(options = {}) {
         return this.deepWriteCandidateStore.listCandidates(options);
@@ -1265,6 +1285,9 @@ export class MemoryKernel {
     rebuildMemoryAtlas(options = {}) {
         return this.memoryAtlasIndexer.rebuild(options);
     }
+    reindexMemoryAtlas(options) {
+        return this.memoryAtlasIndexer.reindex(options);
+    }
     ensureMemoryAtlas(options) {
         return this.memoryAtlasIndexer.ensureFresh(options);
     }
@@ -2002,6 +2025,22 @@ export function createMemoryKernelFromConfig(input = {}) {
     const { configPath: _configPath, cwd: _cwd, env: _env, ...explicitOptions } = options;
     return createMemoryKernel({ ...loaded.options, ...explicitOptions });
 }
+function changedFieldsForRepair(input) {
+    if (input.operation === 'reclassify') {
+        return [
+            input.episodeType ? 'episodeType' : '',
+            input.topicPath ? 'topicPath' : '',
+            input.importance !== undefined ? 'importance' : '',
+        ].filter(Boolean);
+    }
+    if (input.operation === 'move-event')
+        return ['episodeEvents'];
+    if (input.operation === 'split' || input.operation === 'merge')
+        return ['episodeEvents', 'crossRefs'];
+    if (input.operation === 'requeue-dream' || input.operation === 'invalidate-dream-run')
+        return ['dreamQueue'];
+    return [];
+}
 function requiredGovernancePayloadString(payload, field) {
     const value = payload[field];
     if (typeof value !== 'string' || value.trim() === '')