cogmem 3.6.5 → 3.7.0

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;
@@ -134,19 +165,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 +188,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) : [];
+        if (!cards.length && plan.facets.length) {
+            const relaxed = relaxFacetPlan(plan);
+            if (relaxed) {
+                plan = relaxed.plan;
+                cards = this.store.searchCanonicalEpisodeCards(projectId, relaxed.plan, limit);
+                relaxationTrace.push(...relaxed.trace);
+            }
+        }
+        return { plan, cards, relaxationTrace };
     }
     attachEvidence(nodes, projectId, options) {
         return nodes.map((node) => {
@@ -164,6 +218,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) => {
@@ -229,7 +294,61 @@ 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)
+        return null;
+    const monthValue = dayFacet.value.slice(0, 7);
+    return {
+        plan: {
+            ...plan,
+            exactness: 'relaxed',
+            facets: plan.facets.map((facet) => facet === dayFacet ? {
+                ...facet,
+                value: monthValue,
+                label: monthValue,
+                nodeId: facet.nodeId?.replace(dayFacet.value, monthValue),
+                relation: 'OCCURRED_IN',
+                granularity: 'month',
+            } : facet),
+        },
+        trace: [{ from: dayFacet.value, to: monthValue, reason: 'exact day facet had no canonical episode match; relaxed to parent month' }],
+    };
+}
 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

@@ -573,6 +573,9 @@ function runRecall(kernel, args) {
         decisionTrace: result.decisionTrace,
         strategyCapsule,
         narrative: result.narrative,
+        atlasCards: result.atlasCards,
+        relatedButNotSelected: result.relatedButNotSelected,
+        relaxationTrace: result.relaxationTrace,
         items: result.items,
     };
 }
@@ -881,7 +884,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.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.0';
 const LATEST_SCHEMA_VERSION = 27;
 export class MemoryKernel {
     options;

package/dist/host/openclaw/AutoMemoryPluginInstaller.js

@@ -5,7 +5,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveCogmemConfigPath } from '../../config/CogmemConfig.js';
 const PLUGIN_ID = 'cogmem-auto-memory';
-const PLUGIN_VERSION = '0.6.3';
+const PLUGIN_VERSION = '0.7.0';
 function defaultPublicEntrypoint() {
     return join(resolve(dirname(fileURLToPath(import.meta.url)), '../..'), 'public.js');
 }
@@ -992,7 +992,7 @@ function audit(config, record) {
 const plugin = {
   id: PLUGIN_ID,
   name: 'CogMem Auto Memory',
-  version: '0.6.3',
+  version: '${PLUGIN_VERSION}',
   register(api) {
     if (!api || typeof api.on !== 'function') {
       throw new Error('OpenClaw plugin API missing api.on');
@@ -1338,10 +1338,32 @@ async function recallPayload(input, config, kernel, memory, formatStrategyContex
     maxMemoryRatio: Number(config.contextMemoryMaxRatio || 0.25), strategy: strategyCapsule,
     candidates: result.items.map(contextCandidateFromRecallItem),
   });
-  const plannedResult = activationPlan
+  let plannedResult = activationPlan
     ? { ...result, items: activationPlan.selected.map((candidate) => candidate.recallItem) }
     : result;
+  let activationReceipt = activationPlan && activationPlan.receipt;
+  if (activationPlan && Array.isArray(result.items)) {
+    const selectedIds = new Set(plannedResult.items.map((item) => item && item.id).filter(Boolean));
+    const strictFacetItem = (result.decisionTrace && result.decisionTrace.selectedLane === 'facet_graph_raw_ledger')
+      ? result.items.find((item) => item && item.canonicalId && Array.isArray(item.matchedFacets) && item.matchedFacets.length > 0)
+      : undefined;
+    if (strictFacetItem && !selectedIds.has(strictFacetItem.id)) {
+      plannedResult = { ...plannedResult, items: [strictFacetItem, ...plannedResult.items].slice(0, Number(config.limit || 3)) };
+      activationReceipt = {
+        ...(activationReceipt || {}),
+        facetGraphRetained: true,
+        retainedCanonicalId: strictFacetItem.canonicalId,
+        matchedFacets: strictFacetItem.matchedFacets,
+        reason: 'strict_facet_match_must_not_be_silently_dropped',
+      };
+    }
+  }
   const anchorItem = plannedResult.items.find((item) => item && item.sourceAnchor && item.sourceAnchor.eventId);
+  const selectedCanonicalIds = new Set(plannedResult.items.map((item) => item && item.canonicalId).filter(Boolean));
+  const selectedEpisodeCards = Array.isArray(result.atlasCards)
+    ? result.atlasCards.filter((card) => card && selectedCanonicalIds.has(card.canonicalId))
+    : [];
+  plannedResult = { ...plannedResult, atlasCards: selectedEpisodeCards };
   const recallContext = formatRecallContext(plannedResult, config);
   return {
     context: recallContext ? (strategyCapsule ? formatStrategyContext(strategyCapsule) + '\n\n' : '') + recallContext : '',
@@ -1349,7 +1371,9 @@ async function recallPayload(input, config, kernel, memory, formatStrategyContex
     recallMode: result.recallMode, fallbackUsed: result.fallbackUsed, intent: input.intent || 'memory_recall',
     anchorEventId: anchorItem && anchorItem.sourceAnchor && anchorItem.sourceAnchor.eventId,
     anchorText: anchorItem && anchorItem.text, queryPlan: result.queryPlan, decisionTrace: result.decisionTrace,
-    activationReceipt: activationPlan && activationPlan.receipt, strategyCapsule,
+    atlasCards: result.atlasCards, selectedEpisodeCards,
+    relatedButNotSelected: result.relatedButNotSelected, relaxationTrace: result.relaxationTrace,
+    activationReceipt, strategyCapsule,
     strategyReplanned: replan.replanned, strategyReplanReason: replan.reason,
     recallLatencyMs: Date.now() - recallStartedAt,
   };
@@ -1394,16 +1418,27 @@ function stripCogmemRecallBlocks(text) {
 
 function formatAtlasContext(result, maxChars) {
   const nodes = Array.isArray(result && result.nodes) ? result.nodes : [];
-  if (!nodes.length) return '';
+  const cards = Array.isArray(result && result.cards) ? result.cards : [];
+  if (!nodes.length && !cards.length) return '';
   const edges = Array.isArray(result && result.edges) ? result.edges : [];
   const actions = Array.isArray(result && result.nextActions) ? result.nextActions : [];
   const nodeDetails = Array.isArray(result && result.nodeDetails) ? result.nodeDetails : [];
   const lines = [
-    '<COGMEM_MEMORY_ATLAS version="memory_atlas.v1" volatile="true" persistence="forbidden" evidence_authority="raw_event_ids_only">',
+    '<COGMEM_MEMORY_ATLAS version="memory_atlas.v2" volatile="true" persistence="forbidden" evidence_authority="raw_event_ids_only">',
     'Bounded navigation map; use it to choose nodes and paths, not as durable evidence.',
-    'Matched facets: ' + safeAtlasText(JSON.stringify(result.facets || {}), 1000),
+    'Matched facets: ' + safeAtlasText(JSON.stringify(result.facets && result.facets.planner || result.facets || {}), 1400),
     'Cold memory resurrected: ' + String(result.coldMemoryResurrected === true),
     '',
+    'Selected memory cards:',
+    ...cards.slice(0, 8).map((card) => '- ' + formatAtlasCard(card)),
+    ...(cards.length ? [
+      '',
+      'Related but not selected:',
+      ...cards.flatMap((card) => Array.isArray(card.relatedButNotSelected) ? card.relatedButNotSelected : [])
+        .slice(0, 8)
+        .map((card) => '- ' + safeAtlasText(card.displayTitle, 160) + ' [' + safeAtlasText(card.reason, 160) + ']'),
+      '',
+    ] : []),
     'Nodes:',
     ...nodes.slice(0, 30).map((node) => '- ' + JSON.stringify({
       id: safeAtlasText(node.id, 500), type: safeAtlasText(node.nodeType, 80),
@@ -1695,6 +1730,9 @@ function compactRecallItems(items, config) {
     projectId: item.projectId,
     sourceAnchor: item.sourceAnchor,
     whyMatched: item.whyMatched,
+    canonicalId: item.canonicalId,
+    displayTitle: item.displayTitle,
+    matchedFacets: item.matchedFacets,
   }));
 }
 
@@ -1731,6 +1769,15 @@ function formatRecallContext(result, config) {
   if (result.decisionTrace) {
     lines.push('recallDecision=' + formatRecallDecision(result.decisionTrace));
   }
+  if (Array.isArray(result.atlasCards) && result.atlasCards.length) {
+    lines.push('selectedMemoryCards=' + result.atlasCards.slice(0, Number(config.memoryContextMaxItems || config.limit || 3)).map(formatAtlasCard).join(' | '));
+  }
+  if (Array.isArray(result.relaxationTrace) && result.relaxationTrace.length) {
+    lines.push('relaxationTrace=' + result.relaxationTrace.map((step) => step.from + ' -> ' + step.to + ' (' + step.reason + ')').join(' | '));
+  }
+  if (Array.isArray(result.relatedButNotSelected) && result.relatedButNotSelected.length) {
+    lines.push('relatedButNotSelected=' + result.relatedButNotSelected.slice(0, 4).map((item) => item.displayTitle + ' [' + item.reason + ']').join(' | '));
+  }
   lines.push('');
   if (result.narrative && result.narrative.summary) {
     lines.push(result.narrative.summary);
@@ -1748,7 +1795,11 @@ function formatRecallContext(result, config) {
       + (item.sourceAnchor.sessionId ? '; session=' + item.sourceAnchor.sessionId : '')
       + (item.sourceAnchor.role ? '; role=' + item.sourceAnchor.role : '') : '';
     const why = item.whyMatched ? '; whyMatched=' + item.whyMatched : '';
-    lines.push('  sourceType=' + sourceType + '; confidence=' + confidence + '; canAnswerExactQuote=' + quote + anchor + why);
+    const canonical = item.canonicalId ? '; canonicalId=' + item.canonicalId : '';
+    const matchedFacets = Array.isArray(item.matchedFacets) && item.matchedFacets.length
+      ? '; matchedFacets=' + item.matchedFacets.map((facet) => facet.type + ':' + facet.value).join(',')
+      : '';
+    lines.push('  sourceType=' + sourceType + '; confidence=' + confidence + '; canAnswerExactQuote=' + quote + canonical + matchedFacets + anchor + why);
     if (item.sourceContext && item.sourceContext.event) {
       const anchorEvent = item.sourceContext.event;
       const anchorFormatted = formatContextEvent(anchorEvent, Math.min(220, sourceWindowMaxChars));
@@ -1801,6 +1852,24 @@ function formatRecallDecision(trace) {
     + ',raw:' + Number(counts.rawLedger || 0);
 }
 
+function formatAtlasCard(card) {
+  const facets = Array.isArray(card && card.matchedFacets)
+    ? card.matchedFacets.map((facet) => facet.type + ':' + facet.value).join(',')
+    : '';
+  const paths = Array.isArray(card && card.matchedPaths)
+    ? card.matchedPaths.map((path) => path.relation + '@' + (path.facet && path.facet.nodeId || 'facet')).slice(0, 6).join(',')
+    : '';
+  const locator = card && card.sourceLocator && card.sourceLocator.command ? '; sourceLocator=' + card.sourceLocator.command : '';
+  const why = card && card.whyMatched ? '; whyMatched=' + truncateLineWithMeta(card.whyMatched, 180).text : '';
+  return (card && card.canonicalId || 'episode:unknown')
+    + '; title=' + truncateLineWithMeta(card && card.displayTitle, 120).text
+    + '; summary=' + truncateLineWithMeta(card && card.oneLineSummary, 180).text
+    + (facets ? '; matchedFacets=' + facets : '')
+    + (paths ? '; matchedPaths=' + paths : '')
+    + why
+    + locator;
+}
+
 function clampRecallContext(text, maxChars) {
   const closingTag = '</COGMEM_RECALL_CONTEXT>';
   if (text.length <= maxChars) return text;

package/dist/mcp/server.js

@@ -5,7 +5,7 @@ import { callCogmemMcpTool, listCogmemMcpTools, } from './CoreMcpTools.js';
 export function createCogmemMcpServer(runtime = {}) {
     const server = new Server({
         name: 'cogmem-core',
-        version: '3.6.5',
+        version: '3.7.0',
     }, {
         capabilities: {
             tools: {},

package/dist/store/MemoryAtlasStore.d.ts

@@ -1,5 +1,8 @@
 import type Database from 'bun:sqlite';
-import type { MemoryAtlasAction, MemoryAtlasEdge, MemoryAtlasNode } from '../atlas/MemoryAtlasTypes.js';
+import type { FacetQueryPlan } from '../atlas/FacetQueryPlanner.js';
+import type { MemoryAtlasAction, MemoryAtlasCard, MemoryAtlasEdge, MemoryAtlasNode, MemoryAtlasRelatedCard } from '../atlas/MemoryAtlasTypes.js';
+export declare const MEMORY_ATLAS_PROJECTION_NAME = "memory_atlas.v2";
+export declare const MEMORY_ATLAS_PROJECTION_SCHEMA_VERSION = "3.7.0";
 export declare class MemoryAtlasStore {
     readonly db: Database;
     constructor(db: Database);
@@ -18,6 +21,9 @@ export declare class MemoryAtlasStore {
         keywords?: string[];
         targetNodeIds?: string[];
     }): MemoryAtlasNode[];
+    searchCanonicalEpisodeCards(projectId: string, plan: FacetQueryPlan, limit: number): MemoryAtlasCard[];
+    relatedEpisodeCards(projectId: string, canonicalId: string, selectedIds: Set<string>, limit: number): MemoryAtlasRelatedCard[];
+    private topicRelatedCardsForPlan;
     resolveTargetNodeIds(projectId: string, query: string): {
         nodeIds: string[];
         entitySourceIds: string[];
@@ -56,5 +62,8 @@ export declare class MemoryAtlasStore {
     countDocuments(projectId?: string): number;
     private refreshFtsNode;
     private topicRelationEdges;
+    private episodeEdgesForFacet;
+    private episodeRows;
+    private cardFromEpisodeRow;
 }
 //# sourceMappingURL=MemoryAtlasStore.d.ts.map