cogmem 3.6.4 → 3.7.0

package/dist/bin/memory.js

@@ -55,6 +55,8 @@ function readArgs(argv) {
         before: numberArg(values, 'before'),
         after: numberArg(values, 'after'),
         sinceGlobalSeq: numberArg(values, 'since') ?? numberArg(values, 'since-global-seq'),
+        untilGlobalSeq: numberArg(values, 'until') ?? numberArg(values, 'until-global-seq'),
+        order: orderArg(values, 'order'),
         intervalMs: numberArg(values, 'interval-ms'),
         maxRuns: numberArg(values, 'max-runs'),
         promoteLimit: numberArg(values, 'promote-limit'),
@@ -75,6 +77,7 @@ function usage() {
         '',
         'Commands:',
         '  status               summarize raw ledger, vector, and dream backlog state',
+        '  plan                 summarize status as agent-safe next actions',
         '  list                 list raw ledger events with source anchors',
         '  search --query <q>   search raw ledger text without requiring hot vectors',
         '  recall --query <q>   run agent-facing governed recall with source context',
@@ -101,7 +104,9 @@ function usage() {
         '  --thread <id>        scope to one thread',
         '  --session <id>       scope to one session',
         '  --limit <n>          result limit, default 20',
-        '  --since <globalSeq>  for bind, scan raw events at or after a global sequence',
+        '  --since <globalSeq>  list/bind events at or after a global sequence',
+        '  --until <globalSeq>  list events at or before a global sequence',
+        '  --order <asc|desc>   list raw ledger order, default desc',
         '  --status <status>    candidate queue status, default candidate',
         '  --id <candidate>     candidate id for review',
         '  --action <action>    review action: approve, reject, defer, supersede, or relink',
@@ -117,7 +122,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, or forensic_quote',
+        '  --intent <intent>    memory_recall, previous_session_summary, forensic_quote, or historical_discussion',
         '  --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',
@@ -135,6 +140,7 @@ function usage() {
 }
 function isMemoryCommand(value) {
     return value === 'status'
+        || value === 'plan'
         || value === 'list'
         || value === 'search'
         || value === 'recall'
@@ -166,9 +172,17 @@ function recallIntentArg(values, key) {
     const raw = stringArg(values, key);
     if (!raw)
         return undefined;
-    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote')
+    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote' || raw === 'historical_discussion')
         return raw;
-    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote`);
+    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote, historical_discussion`);
+}
+function orderArg(values, key) {
+    const raw = stringArg(values, key);
+    if (!raw)
+        return undefined;
+    if (raw === 'asc' || raw === 'desc')
+        return raw;
+    throw new Error(`--${key} must be one of asc, desc`);
 }
 function stringArg(values, key) {
     const value = values[key];
@@ -219,30 +233,32 @@ function inspectionDbPath(args) {
 function runReadOnlyInspection(args) {
     const inspection = new MemoryInspectionStore(inspectionDbPath(args));
     try {
-        if (args.command === 'status') {
+        if (args.command === 'status' || args.command === 'plan') {
             const payload = inspection.status({
                 projectId: args.projectId, workspaceId: args.workspaceId,
                 threadId: args.threadId, sessionId: args.sessionId,
             });
+            const queueSummary = buildCandidateQueueSummary(inspection, args.projectId, args.limit || 5000);
+            const plan = buildMemoryPlan(payload, queueSummary, args.projectId);
+            const enrichedPayload = args.command === 'plan'
+                ? plan
+                : { ...payload, queueSummary, nextActions: plan.nextActions, blocking: plan.blocking, nonBlocking: plan.nonBlocking };
             if (args.json) {
-                printCliJson('memory.status', payload, {
+                printCliJson(`memory.${args.command}`, enrichedPayload, {
                     queue: payload.dreamCandidateQueue,
                     beliefs: payload.activeBeliefs,
                 });
             }
             else
-                printHuman('status', payload);
+                printHuman(args.command, enrichedPayload);
             return;
         }
-        const status = args.status || 'candidate';
-        const candidates = inspection.listCandidates({
-            projectId: args.projectId,
-            status,
-            limit: args.limit || 50,
-        });
-        const payload = { total: candidates.length, status, candidates: candidates.map(candidateToJson) };
+        const queueSummary = buildCandidateQueueSummary(inspection, args.projectId, args.limit || 50);
+        const payload = args.status
+            ? buildSpecificCandidatePayload(inspection, args.projectId, args.status, args.limit || 50, queueSummary)
+            : buildGroupedCandidatePayload(queueSummary);
         if (args.json)
-            printCliJson('memory.candidates', payload);
+            printCliJson('memory.candidates', payload, { queue: queueSummary });
         else
             printHuman('candidates', payload);
     }
@@ -262,6 +278,7 @@ function eventText(event) {
 }
 function eventToJson(event) {
     const text = eventText(event);
+    const locator = eventSourceLocator(event, 2, 2);
     return {
         eventId: event.eventId,
         label: memoryEventLabel(event),
@@ -294,6 +311,21 @@ function eventToJson(event) {
             causalityType: event.causalityType,
             orderingConfidence: event.orderingConfidence,
         },
+        sourceLocator: locator,
+    };
+}
+function eventSourceLocator(event, before, after) {
+    const projectArg = event.projectId ? ` --project ${cliArg(event.projectId)}` : '';
+    const base = `cogmem memory show --event ${cliArg(event.eventId)}${projectArg}`;
+    return {
+        eventId: event.eventId,
+        globalSeq: event.globalSeq,
+        projectId: event.projectId,
+        threadId: event.threadId,
+        sessionId: event.sessionId,
+        localDate: event.localDate,
+        command: `${base} --before ${before} --after ${after} --json`,
+        contextCommand: `${base} --before 3 --after 3 --json`,
     };
 }
 function candidateToJson(candidate) {
@@ -313,6 +345,141 @@ function candidateToJson(candidate) {
         updatedAt: candidate.updatedAt,
     };
 }
+function buildCandidateQueueSummary(inspection, projectId, limit) {
+    const status = inspection.status({ projectId });
+    const queue = status.dreamCandidateQueue;
+    const candidateRows = inspection.listCandidates({ projectId, status: 'candidate', limit });
+    const needsRows = inspection.listCandidates({ projectId, status: 'needs_confirmation', limit: Math.max(limit, 5000) });
+    const now = Date.now();
+    const deferredRows = needsRows.filter((candidate) => candidate.reviewAfter !== undefined && candidate.reviewAfter > now);
+    const activeNeedsRows = needsRows.filter((candidate) => !(candidate.reviewAfter !== undefined && candidate.reviewAfter > now));
+    return {
+        candidate: queue.candidate,
+        needs_confirmation: queue.needsConfirmation,
+        activeNeedsConfirmation: Math.max(0, queue.needsConfirmation - deferredRows.length),
+        deferredNeedsConfirmation: deferredRows.length,
+        promoted: queue.promoted,
+        rejected: queue.rejected,
+        superseded: queue.superseded,
+        shadow: queue.shadow,
+        groups: {
+            candidate: candidateRows.slice(0, limit).map(candidateToJson),
+            needs_confirmation: activeNeedsRows.slice(0, limit).map(candidateToJson),
+            deferred: deferredRows.slice(0, limit).map(candidateToJson),
+        },
+    };
+}
+function buildSpecificCandidatePayload(inspection, projectId, status, limit, queueSummary) {
+    const candidates = inspection.listCandidates({ projectId, status, limit });
+    const payload = {
+        total: candidates.length,
+        status,
+        candidates: candidates.map(candidateToJson),
+        queueSummary,
+    };
+    if (status === 'candidate') {
+        payload.warning = 'This lists only status=candidate. Use memory candidates without --status for grouped candidate and needs_confirmation queues.';
+    }
+    else if (status === 'needs_confirmation') {
+        payload.warning = 'memory govern does not process needs_confirmation. Use memory review with explicit user evidence, or defer with review_after.';
+    }
+    return payload;
+}
+function buildGroupedCandidatePayload(queueSummary) {
+    return {
+        total: queueSummary.groups.candidate.length + queueSummary.groups.needs_confirmation.length + queueSummary.groups.deferred.length,
+        status: 'grouped',
+        queueSummary,
+        groups: queueSummary.groups,
+        nextActions: candidateNextActions(queueSummary, undefined),
+    };
+}
+function buildMemoryPlan(status, queueSummary, projectId) {
+    const nextActions = [];
+    const blocking = [];
+    const nonBlocking = [];
+    const projectArg = projectId ? ` --project ${cliArg(projectId)}` : '';
+    const episodeDream = status.episodeDream;
+    const pendingEpisodes = asCount(episodeDream.pending) + asCount(episodeDream.retryScheduled);
+    const undreamedRawCount = asCount(status.undreamedRawCount);
+    if (pendingEpisodes > 0) {
+        nextActions.push({
+            priority: 'high',
+            type: 'dream_tick',
+            safeForAutomation: true,
+            reason: `${pendingEpisodes} sealed episode Dream jobs can be processed`,
+            command: `cogmem dream tick${projectArg} --mode auto --max-episodes 20 --json`,
+        });
+    }
+    if (undreamedRawCount > 0) {
+        nonBlocking.push({
+            type: 'raw_dream_ledger_lag',
+            count: undreamedRawCount,
+            episodeDreamPending: pendingEpisodes,
+            resolvableByDreamTick: false,
+            safeForAutomation: false,
+            reason: pendingEpisodes > 0
+                ? 'Raw ledger dream coverage is tracked separately from sealed episode Dream jobs; dream tick may process episodes but does not guarantee this counter will clear.'
+                : 'Raw ledger dream coverage is behind, but there are no sealed episode Dream jobs. Do not run dream tick for this signal alone.',
+            command: `cogmem memory list${projectArg} --order asc --limit 20 --json`,
+        });
+    }
+    nextActions.push(...candidateNextActions(queueSummary, projectId));
+    if (queueSummary.activeNeedsConfirmation > 0) {
+        blocking.push({
+            type: 'needs_confirmation',
+            count: queueSummary.activeNeedsConfirmation,
+            reason: 'Manual review requires explicit user evidence; memory govern will not process these candidates.',
+            command: `cogmem memory candidates${projectArg} --status needs_confirmation --json`,
+        });
+    }
+    if (queueSummary.deferredNeedsConfirmation > 0) {
+        nonBlocking.push({
+            type: 'deferred_confirmation',
+            count: queueSummary.deferredNeedsConfirmation,
+            reason: 'Deferred needs_confirmation remains in the review queue until review_after.',
+            command: `cogmem memory candidates${projectArg} --json`,
+        });
+    }
+    return {
+        healthy: nextActions.length === 0 && blocking.length === 0,
+        projectId,
+        queueSummary,
+        dreamBacklog: status.dreamBacklog,
+        episodeDream: status.episodeDream,
+        vectorState: status.vectorState,
+        nextActions,
+        blocking,
+        nonBlocking,
+    };
+}
+function candidateNextActions(queueSummary, projectId) {
+    const projectArg = projectId ? ` --project ${cliArg(projectId)}` : '';
+    const actions = [];
+    if (queueSummary.candidate > 0) {
+        actions.push({
+            priority: 'high',
+            type: 'govern',
+            safeForAutomation: true,
+            reason: `${queueSummary.candidate} ordinary candidates are ready for deterministic governance`,
+            command: `cogmem memory govern${projectArg} --limit 100 --json`,
+        });
+    }
+    if (queueSummary.activeNeedsConfirmation > 0) {
+        actions.push({
+            priority: 'medium',
+            type: 'review_needs_confirmation',
+            safeForAutomation: false,
+            reason: `${queueSummary.activeNeedsConfirmation} candidates need explicit operator/user confirmation`,
+            command: `cogmem memory candidates${projectArg} --status needs_confirmation --json`,
+            reviewCommand: `cogmem memory review${projectArg} --id <candidate-id> --action <approve|reject|defer|supersede|relink> --actor <operator> --reason <reason> --json`,
+        });
+    }
+    return actions;
+}
+function asCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
 function runStatus(kernel, args) {
     const page = kernel.eventStore.queryEvents(1, 1, {
         projectId: args.projectId ? [args.projectId] : undefined,
@@ -344,9 +511,15 @@ function runList(kernel, args) {
         workspaceId: args.workspaceId ? [args.workspaceId] : undefined,
         threadId: args.threadId ? [args.threadId] : undefined,
         sessionId: args.sessionId ? [args.sessionId] : undefined,
+        sinceGlobalSeq: args.sinceGlobalSeq,
+        untilGlobalSeq: args.untilGlobalSeq,
+        order: args.order,
     });
     return {
         total: page.total,
+        sinceGlobalSeq: args.sinceGlobalSeq,
+        untilGlobalSeq: args.untilGlobalSeq,
+        order: args.order || 'desc',
         events: page.records.map(eventToJson),
     };
 }
@@ -400,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,
     };
 }
@@ -607,12 +783,24 @@ function runCandidates(kernel, args) {
     };
 }
 function printHuman(command, payload) {
-    if (command === 'status') {
+    if (command === 'status' || command === 'plan') {
+        if (command === 'plan') {
+            console.log(`healthy: ${payload.healthy}`);
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+            console.log(`nextActions: ${JSON.stringify(payload.nextActions)}`);
+            console.log(`blocking: ${JSON.stringify(payload.blocking)}`);
+            console.log(`nonBlocking: ${JSON.stringify(payload.nonBlocking)}`);
+            return;
+        }
         console.log(`rawEvents: ${payload.rawEventCount}`);
         console.log(`vectors: ${payload.vectorCount}`);
         console.log(`dreamBacklog: ${JSON.stringify(payload.dreamBacklog)}`);
         console.log(`episodeDream: ${JSON.stringify(payload.episodeDream)}`);
         console.log(`dreamCandidateQueue: ${JSON.stringify(payload.dreamCandidateQueue)}`);
+        if (payload.queueSummary)
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+        if (payload.nextActions)
+            console.log(`nextActions: ${JSON.stringify(payload.nextActions)}`);
         return;
     }
     if (command === 'dream') {
@@ -646,6 +834,18 @@ function printHuman(command, payload) {
         return;
     }
     if (command === 'candidates') {
+        if (payload.queueSummary)
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+        const groups = payload.groups;
+        if (groups) {
+            for (const [group, values] of Object.entries(groups)) {
+                console.log(`${group}: ${values.length}`);
+                for (const candidate of values) {
+                    console.log(`- ${candidate.candidateId} ${candidate.candidateType} ${candidate.status} confidence=${candidate.confidence}`);
+                }
+            }
+            return;
+        }
         const candidates = Array.isArray(payload.candidates) ? payload.candidates : [];
         for (const candidate of candidates) {
             console.log(`- ${candidate.candidateId} ${candidate.candidateType} ${candidate.status} confidence=${candidate.confidence}`);
@@ -684,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
@@ -741,7 +941,7 @@ async function main() {
         console.log(usage());
         return;
     }
-    if (args.command === 'status' || args.command === 'candidates') {
+    if (args.command === 'status' || args.command === 'plan' || args.command === 'candidates') {
         runReadOnlyInspection(args);
         return;
     }
@@ -801,3 +1001,6 @@ main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
 });
+function cliArg(value) {
+    return /^[A-Za-z0-9._:/=@+-]+$/u.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/factory.d.ts

@@ -138,6 +138,8 @@ export interface MemoryBindingBackfillOptions {
 export interface MemoryBindingBackfillResult {
     projectId?: string;
     sinceGlobalSeq?: number;
+    nextGlobalSeq?: number;
+    hasMore: boolean;
     scannedEvents: number;
     bindableEvents: number;
     boundEvents: number;

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.4';
+const CORE_VERSION = '3.7.0';
 const LATEST_SCHEMA_VERSION = 27;
 export class MemoryKernel {
     options;
@@ -1195,18 +1195,22 @@ export class MemoryKernel {
     }
     bindRawEvents(options = {}) {
         const limit = Math.max(1, Math.min(options.limit ?? 500, 5000));
-        const page = this.eventStore.queryEvents(1, limit, {
-            projectId: options.projectId ? [options.projectId] : undefined,
-            workspaceId: options.workspaceId ? [options.workspaceId] : undefined,
-            threadId: options.threadId ? [options.threadId] : undefined,
-            sessionId: options.sessionId ? [options.sessionId] : undefined,
+        const afterGlobalSeq = options.sinceGlobalSeq === undefined
+            ? undefined
+            : Math.max(-1, options.sinceGlobalSeq - 1);
+        const records = this.eventStore.listRawEventsAfterGlobalSeq({
+            projectId: options.projectId,
+            workspaceId: options.workspaceId,
+            threadId: options.threadId,
+            sessionId: options.sessionId,
+            afterGlobalSeq,
+            limit,
         });
-        const records = page.records
-            .filter((event) => options.sinceGlobalSeq === undefined || (event.globalSeq || 0) >= options.sinceGlobalSeq)
-            .sort((a, b) => (a.globalSeq || 0) - (b.globalSeq || 0));
         const result = {
             projectId: options.projectId,
             sinceGlobalSeq: options.sinceGlobalSeq,
+            nextGlobalSeq: records.at(-1)?.globalSeq,
+            hasMore: records.length >= limit,
             scannedEvents: records.length,
             bindableEvents: 0,
             boundEvents: 0,
@@ -1325,16 +1329,30 @@ export class MemoryKernel {
         return { touched: this.memoryAtlasStore.recordAccess(input.projectId, valid, input.reason, input.query, input.now) };
     }
     countUnboundBindableRawEvents(projectId, limit = 1000) {
-        const page = this.eventStore.queryEvents(1, Math.max(1, limit), {
-            projectId: projectId ? [projectId] : undefined,
-        });
+        const max = Math.max(1, limit);
+        let afterGlobalSeq;
         let count = 0;
-        for (const event of page.records) {
-            if (!this.memoryBindingService.isBindableRawEvent(event))
-                continue;
-            if (this.memoryBindingStore.listBindings({ eventId: event.eventId, limit: 1 }).length > 0)
-                continue;
-            count += 1;
+        while (count < max) {
+            const batchLimit = Math.min(500, max);
+            const events = this.eventStore.listRawEventsAfterGlobalSeq({
+                projectId,
+                afterGlobalSeq,
+                limit: batchLimit,
+            });
+            if (events.length === 0)
+                break;
+            afterGlobalSeq = events.at(-1)?.globalSeq ?? afterGlobalSeq;
+            for (const event of events) {
+                if (!this.memoryBindingService.isBindableRawEvent(event))
+                    continue;
+                if (this.memoryBindingStore.listBindings({ eventId: event.eventId, limit: 1 }).length > 0)
+                    continue;
+                count += 1;
+                if (count >= max)
+                    break;
+            }
+            if (events.length < batchLimit)
+                break;
         }
         return count;
     }

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');
 }
@@ -26,7 +26,7 @@ export function installOpenClawAutoMemoryPlugin(options) {
         ? { kind: 'toml', path: resolve(options.configPath) }
         : resolveCogmemConfigPath({ cwd: workspaceRoot });
     if (configResolution.kind !== 'toml') {
-        throw new Error(`Missing cogmem config at ${configResolution.path}. Run cogmem-init --agent openclaw --scope project first.`);
+        throw new Error(`Missing cogmem config at ${configResolution.path}. Ask an operator to run the interactive setup: cogmem init --agent openclaw --scope project.`);
     }
     const configPath = configResolution.path;
     const pluginDir = resolve(options.pluginDir || defaultOpenClawAutoMemoryPluginDir(workspaceRoot));
@@ -663,6 +663,9 @@ function classifyRecallIntent(query) {
   if (/原话|怎么说的|完整对话|上一句|下一句|exact quote|verbatim/.test(text)) {
     return 'forensic_quote';
   }
+  if (/记得.{0,12}(聊过|讨论过|说过)|还记得|之前.{0,12}(聊过|讨论过|说过)|以前.{0,12}(聊过|讨论过|说过)|(过去|几个月前|半年前|上个月|前几天|昨天|上次|上个).{0,20}(聊过|讨论过|说过)|当时.{0,12}(聊|说|问)|那次.{0,12}(聊|说|问)|有没有.{0,12}(记录|聊过|讨论过)|have we discussed|did we talk about|previously discussed/.test(text)) {
+    return 'historical_discussion';
+  }
   return 'memory_recall';
 }
 
@@ -989,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');
@@ -1335,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 : '',
@@ -1346,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,
   };
@@ -1391,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),
@@ -1692,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,
   }));
 }
 
@@ -1728,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);
@@ -1745,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));
@@ -1754,7 +1808,8 @@ function formatRecallContext(result, config) {
       if (item.sourceContext.locator && item.sourceContext.locator.command) {
         lines.push('  sourceLocator=' + item.sourceContext.locator.command);
       } else if (item.sourceContext.event.eventId) {
-        lines.push('  sourceLocator=cogmem memory show --event ' + item.sourceContext.event.eventId + ' --before 2 --after 2');
+        const project = item.sourceContext.event.projectId ? ' --project ' + item.sourceContext.event.projectId : '';
+        lines.push('  sourceLocator=cogmem memory show --event ' + item.sourceContext.event.eventId + project + ' --before 2 --after 2 --json');
       }
       const seenEventIds = new Set([anchorEvent.eventId].filter(Boolean));
       const before = uniqueWindowEvents(Array.isArray(item.sourceContext.before) ? item.sourceContext.before : [], seenEventIds).slice(-2);
@@ -1797,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.1',
+        version: '3.7.0',
     }, {
         capabilities: {
             tools: {},