cogmem 3.6.4 → 3.7.0

package/dist/store/EventStore.d.ts

@@ -61,6 +61,9 @@ export declare class EventStore {
     getLatestEvent(): MemoryEvent | null;
     listRawEventsAfterGlobalSeq(options?: {
         projectId?: string;
+        workspaceId?: string;
+        threadId?: string;
+        sessionId?: string;
         afterGlobalSeq?: number;
         limit?: number;
     }): MemoryEvent[];
@@ -78,6 +81,9 @@ export declare class EventStore {
         sessionId?: string[];
         startTime?: number;
         endTime?: number;
+        sinceGlobalSeq?: number;
+        untilGlobalSeq?: number;
+        order?: 'asc' | 'desc';
     }): EventAuditPage;
     getEvent(eventId: string): MemoryEvent | null;
     getThreadEvents(threadId: string, options?: {

package/dist/store/EventStore.js

@@ -270,6 +270,18 @@ export class EventStore {
             conditions.push('project_id = ?');
             params.push(options.projectId);
         }
+        if (options.workspaceId) {
+            conditions.push('workspace_id = ?');
+            params.push(options.workspaceId);
+        }
+        if (options.threadId) {
+            conditions.push('thread_id = ?');
+            params.push(options.threadId);
+        }
+        if (options.sessionId) {
+            conditions.push('session_id = ?');
+            params.push(options.sessionId);
+        }
         if (options.afterGlobalSeq !== undefined) {
             conditions.push('COALESCE(global_seq, 0) > ?');
             params.push(options.afterGlobalSeq);
@@ -347,7 +359,18 @@ export class EventStore {
             conditions.push('occurred_at <= ?');
             params.push(filters.endTime);
         }
+        if (filters?.sinceGlobalSeq !== undefined) {
+            conditions.push('COALESCE(global_seq, 0) >= ?');
+            params.push(filters.sinceGlobalSeq);
+        }
+        if (filters?.untilGlobalSeq !== undefined) {
+            conditions.push('COALESCE(global_seq, 0) <= ?');
+            params.push(filters.untilGlobalSeq);
+        }
         const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+        const orderSql = filters?.order === 'asc'
+            ? 'COALESCE(global_seq, 0) ASC, occurred_at ASC, event_id ASC'
+            : 'COALESCE(global_seq, 0) DESC, occurred_at DESC, event_id DESC';
         const totalRow = this.db.prepare(`
       SELECT COUNT(*) AS count FROM memory_events ${where}
     `).get(...params);
@@ -355,7 +378,7 @@ export class EventStore {
       SELECT ${MEMORY_EVENT_COLUMNS}
       FROM memory_events
       ${where}
-      ORDER BY COALESCE(global_seq, 0) DESC, occurred_at DESC, event_id DESC
+      ORDER BY ${orderSql}
       LIMIT ? OFFSET ?
     `).all(...params, safePageSize, offset);
         return {
@@ -375,7 +398,10 @@ export class EventStore {
                 threadId: filters?.threadId,
                 sessionId: filters?.sessionId,
                 startTime: filters?.startTime,
-                endTime: filters?.endTime
+                endTime: filters?.endTime,
+                sinceGlobalSeq: filters?.sinceGlobalSeq,
+                untilGlobalSeq: filters?.untilGlobalSeq,
+                order: filters?.order,
             }
         };
     }

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

package/dist/store/MemoryAtlasStore.js

@@ -1,4 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
+export const MEMORY_ATLAS_PROJECTION_NAME = 'memory_atlas.v2';
+export const MEMORY_ATLAS_PROJECTION_SCHEMA_VERSION = '3.7.0';
 export class MemoryAtlasStore {
     db;
     constructor(db) {
@@ -82,12 +84,81 @@ export class MemoryAtlasStore {
             return mapNode(row, matches + Number(row.activation || 0));
         }).sort((a, b) => b.score - a.score);
     }
+    searchCanonicalEpisodeCards(projectId, plan, limit) {
+        const plannedFacets = plan.facets;
+        if (!plannedFacets.length)
+            return [];
+        const facetMatches = plannedFacets.map((facet) => ({ facet, rows: this.episodeEdgesForFacet(projectId, facet) }));
+        if (plan.operator === 'intersection' && facetMatches.some((match) => match.rows.length === 0))
+            return [];
+        const candidateIds = plan.operator === 'intersection'
+            ? intersectSets(facetMatches.map((match) => new Set(match.rows.map((row) => row.source_id))))
+            : new Set(facetMatches.flatMap((match) => match.rows.map((row) => row.source_id)));
+        if (!candidateIds.size)
+            return [];
+        const rows = this.episodeRows(projectId, Array.from(candidateIds));
+        const cards = rows.map((row) => {
+            const candidateEdges = facetMatches.flatMap((match) => match.rows.filter((edge) => edge.source_id === row.source_id));
+            return this.cardFromEpisodeRow(row, candidateEdges, projectId);
+        });
+        const selectedIds = new Set(cards.map((card) => card.canonicalId));
+        for (const card of cards) {
+            card.relatedButNotSelected = mergeRelatedCards(this.relatedEpisodeCards(projectId, card.canonicalId, selectedIds, 4), this.topicRelatedCardsForPlan(projectId, plan, selectedIds, 4)).slice(0, 4);
+        }
+        return cards.sort((left, right) => scoreCard(right) - scoreCard(left)).slice(0, Math.max(1, Math.min(limit, 100)));
+    }
+    relatedEpisodeCards(projectId, canonicalId, selectedIds, limit) {
+        const parsed = parseNodeId(canonicalId, projectId);
+        if (!parsed || parsed.type !== 'episode')
+            return [];
+        const rows = this.db.prepare(`
+      SELECT e.relation_type, e.confidence, d.node_id, d.label, d.metadata_json
+      FROM memory_edges e
+      JOIN memory_atlas_documents d ON d.project_id=e.project_id AND d.node_id=CASE
+        WHEN e.source_type='episode' AND e.source_id=? THEN 'episode:' || e.target_id
+        ELSE 'episode:' || e.source_id
+      END
+      WHERE e.project_id=? AND e.status IN ('active','weak') AND e.relation_type IN ('SAME_ISSUE','FOLLOWS_UP','REFINES','CORRECTS','CONTRADICTS','SUPERSEDES','RELATED_TO')
+        AND ((e.source_type='episode' AND e.source_id=?) OR (e.target_type='episode' AND e.target_id=?))
+      ORDER BY CASE e.relation_type WHEN 'SAME_ISSUE' THEN 1 WHEN 'FOLLOWS_UP' THEN 2 WHEN 'REFINES' THEN 3 ELSE 4 END, e.confidence DESC
+      LIMIT ?
+    `).all(parsed.id, projectId, parsed.id, parsed.id, Math.max(1, Math.min(limit * 3, 30)));
+        const result = [];
+        for (const row of rows) {
+            if (selectedIds.has(row.node_id))
+                continue;
+            result.push({
+                canonicalId: row.node_id,
+                displayTitle: row.label,
+                reason: row.relation_type === 'RELATED_TO' ? 'related topic but different issue/date' : row.relation_type.toLowerCase(),
+            });
+            if (result.length >= limit)
+                break;
+        }
+        return result;
+    }
+    topicRelatedCardsForPlan(projectId, plan, selectedIds, limit) {
+        const topicFacets = plan.facets.filter((facet) => facet.type === 'topic');
+        if (!topicFacets.length)
+            return [];
+        const rows = topicFacets.flatMap((facet) => this.episodeEdgesForFacet(projectId, facet));
+        const candidateIds = Array.from(new Set(rows.map((row) => row.source_id))).filter((id) => !selectedIds.has(`episode:${id}`));
+        if (!candidateIds.length)
+            return [];
+        return this.episodeRows(projectId, candidateIds)
+            .map((row) => ({
+            canonicalId: row.node_id,
+            displayTitle: row.label,
+            reason: 'related topic but different issue/date',
+        }))
+            .slice(0, Math.max(1, Math.min(limit, 20)));
+    }
     resolveTargetNodeIds(projectId, query) {
         const normalizedQuery = normalizeLookup(query);
         const candidates = this.db.prepare(`
       SELECT node_id,node_type,source_id,label,topic_path,metadata_json,evidence_event_ids_json
       FROM memory_atlas_documents
-      WHERE project_id=? AND node_type IN ('entity','topic','project') AND status NOT IN ('rejected','archived')
+      WHERE project_id=? AND node_type IN ('entity','topic','issue','project') AND status NOT IN ('rejected','archived')
     `).all(projectId);
         const seeds = [];
         const labels = [];
@@ -375,12 +446,34 @@ export class MemoryAtlasStore {
     }
     projectionNeedsRefresh(projectId) {
         const row = this.db.prepare(`
+      SELECT status, metadata_json FROM memory_atlas_projection_state
+      WHERE project_id=? AND projection_name=?
+    `).get(projectId, MEMORY_ATLAS_PROJECTION_NAME);
+        if (!row || row.status !== 'clean')
+            return true;
+        const metadata = parseMetadata(row.metadata_json);
+        if (metadata.projectionSchemaVersion !== MEMORY_ATLAS_PROJECTION_SCHEMA_VERSION)
+            return true;
+        const legacyDirty = this.db.prepare(`
       SELECT status FROM memory_atlas_projection_state
-      WHERE project_id=? AND projection_name='memory_atlas.v1'
+      WHERE project_id=? AND projection_name='memory_atlas.v1' AND status<>'clean'
     `).get(projectId);
-        return !row || row.status !== 'clean';
+        return Boolean(legacyDirty);
     }
     markProjectionClean(projectId, metadata = {}, now = Date.now()) {
+        const enrichedMetadata = {
+            ...metadata,
+            projectionName: MEMORY_ATLAS_PROJECTION_NAME,
+            projectionSchemaVersion: MEMORY_ATLAS_PROJECTION_SCHEMA_VERSION,
+        };
+        this.db.prepare(`
+      INSERT INTO memory_atlas_projection_state(
+        project_id, projection_name, cursor_value, status, last_rebuild_at, last_error, metadata_json
+      ) VALUES(?, ?, ?, 'clean', ?, NULL, ?)
+      ON CONFLICT(project_id, projection_name) DO UPDATE SET
+        cursor_value=excluded.cursor_value, status='clean', last_rebuild_at=excluded.last_rebuild_at,
+        last_error=NULL, metadata_json=excluded.metadata_json
+    `).run(projectId, MEMORY_ATLAS_PROJECTION_NAME, String(now), now, JSON.stringify(enrichedMetadata));
         this.db.prepare(`
       INSERT INTO memory_atlas_projection_state(
         project_id, projection_name, cursor_value, status, last_rebuild_at, last_error, metadata_json
@@ -388,17 +481,20 @@ export class MemoryAtlasStore {
       ON CONFLICT(project_id, projection_name) DO UPDATE SET
         cursor_value=excluded.cursor_value, status='clean', last_rebuild_at=excluded.last_rebuild_at,
         last_error=NULL, metadata_json=excluded.metadata_json
-    `).run(projectId, String(now), now, JSON.stringify(metadata));
+    `).run(projectId, String(now), now, JSON.stringify({ compatibilityAliasFor: MEMORY_ATLAS_PROJECTION_NAME }));
     }
     markProjectionFailed(projectId, error, now = Date.now()) {
         this.db.prepare(`
       INSERT INTO memory_atlas_projection_state(project_id,projection_name,status,last_rebuild_at,last_error,metadata_json)
-      VALUES(?,'memory_atlas.v1','error',?,?,'{}')
+      VALUES(?,?,'error',?,?,?)
       ON CONFLICT(project_id,projection_name) DO UPDATE SET status='error',last_rebuild_at=excluded.last_rebuild_at,last_error=excluded.last_error
-    `).run(projectId, now, error.slice(0, 2000));
+    `).run(projectId, MEMORY_ATLAS_PROJECTION_NAME, now, error.slice(0, 2000), JSON.stringify({
+            projectionName: MEMORY_ATLAS_PROJECTION_NAME,
+            projectionSchemaVersion: MEMORY_ATLAS_PROJECTION_SCHEMA_VERSION,
+        }));
     }
     getProjectionState(projectId) {
-        const row = this.db.prepare(`SELECT status,last_rebuild_at,last_error FROM memory_atlas_projection_state WHERE project_id=? AND projection_name='memory_atlas.v1'`).get(projectId);
+        const row = this.db.prepare(`SELECT status,last_rebuild_at,last_error FROM memory_atlas_projection_state WHERE project_id=? AND projection_name=?`).get(projectId, MEMORY_ATLAS_PROJECTION_NAME);
         return row ? { status: row.status, lastRebuildAt: row.last_rebuild_at ?? undefined, lastError: row.last_error || undefined } : null;
     }
     listKnownProjectIds() {
@@ -436,6 +532,60 @@ export class MemoryAtlasStore {
             target: nodeId('topic', row.target_path, projectId), confidence: Number(row.confidence),
             evidenceEventIds: parseStringArray(row.evidence_event_ids_json) }));
     }
+    episodeEdgesForFacet(projectId, facet) {
+        const relationFilter = facet.relation ? 'AND relation_type=?' : '';
+        const params = facet.relation
+            ? [projectId, facet.type, facet.value, facet.relation]
+            : [projectId, facet.type, facet.value];
+        return this.db.prepare(`
+      SELECT source_id, relation_type, target_type, target_id, confidence, evidence_event_ids_json
+      FROM memory_edges
+      WHERE project_id=? AND source_type='episode' AND target_type=? AND target_id=? ${relationFilter}
+        AND status IN ('active','weak')
+      ORDER BY confidence DESC
+      LIMIT 5000
+    `).all(...params);
+    }
+    episodeRows(projectId, episodeIds) {
+        const bounded = Array.from(new Set(episodeIds)).slice(0, 500);
+        if (!bounded.length)
+            return [];
+        return this.db.prepare(`
+      SELECT d.*, COALESCE(a.activation, 0) AS activation
+      FROM memory_atlas_documents d LEFT JOIN memory_atlas_activation a
+        ON a.project_id=d.project_id AND a.node_id=d.node_id
+      WHERE d.project_id=? AND d.node_id IN (${bounded.map(() => '?').join(',')})
+        AND d.node_type='episode' AND d.status NOT IN ('rejected','archived')
+    `).all(projectId, ...bounded.map((id) => `episode:${id}`));
+    }
+    cardFromEpisodeRow(row, edges, projectId) {
+        const metadata = parseMetadata(row.metadata_json);
+        const evidenceEventIds = parseStringArray(row.evidence_event_ids_json);
+        const matchedFacets = edges.map((edge) => facetFromEdge(edge, projectId));
+        const matchedPaths = edges.map((edge) => {
+            const facet = facetFromEdge(edge, projectId);
+            return { facet, via: [facet.nodeId, row.node_id], relation: edge.relation_type, confidence: Number(edge.confidence || 0) };
+        });
+        const issueHints = stringArray(metadata.issueHints);
+        const topicHints = stringArray(metadata.topicHints);
+        return {
+            canonicalId: row.node_id,
+            nodeType: 'episode',
+            displayTitle: row.label,
+            oneLineSummary: row.summary || undefined,
+            matchedFacets,
+            matchedPaths,
+            parentTopics: topicHints.length ? topicHints : row.topic_path ? [row.topic_path] : [],
+            issueType: issueHints[0],
+            eventKind: optionalMetadataString(metadata.eventKind),
+            localDate: optionalMetadataString(metadata.localDate) ?? (row.occurred_at ? new Date(row.occurred_at).toISOString().slice(0, 10) : undefined),
+            whyMatched: matchedFacets.length ? `matched ${matchedFacets.map((facet) => `${facet.type}:${facet.value}`).join(', ')}` : 'matched canonical episode',
+            relatedButNotSelected: [],
+            evidenceEventIds,
+            evidenceTotal: evidenceEventIds.length,
+            evidenceReturned: 0,
+        };
+    }
 }
 function mapNode(row, score) {
     return { id: row.node_id, projectId: row.project_id, nodeType: row.node_type, sourceId: row.source_id,
@@ -479,7 +629,7 @@ catch {
 } }
 function escapeLike(value) { return value.replace(/[\\%_]/g, '\\$&'); }
 function nodeId(type, id, projectId) {
-    if (type === 'topic' || type === 'time')
+    if (['topic', 'time', 'issue', 'session', 'thread', 'memoryKind', 'actionKind'].includes(type))
         return `${type}:${projectId}:${id}`;
     return `${type}:${id}`;
 }
@@ -487,14 +637,78 @@ function timeNodeId(projectId, occurredAt) {
     return `time:${projectId}:${new Date(occurredAt).getUTCFullYear()}`;
 }
 function parseNodeId(value, projectId) {
-    const topicPrefix = `topic:${projectId}:`;
-    if (value.startsWith(topicPrefix))
-        return { type: 'topic', id: value.slice(topicPrefix.length) };
-    const timePrefix = `time:${projectId}:`;
-    if (value.startsWith(timePrefix))
-        return { type: 'time', id: value.slice(timePrefix.length) };
+    for (const type of ['topic', 'time', 'issue', 'session', 'thread', 'memoryKind', 'actionKind']) {
+        const prefix = `${type}:${projectId}:`;
+        if (value.startsWith(prefix))
+            return { type, id: value.slice(prefix.length) };
+    }
     const separator = value.indexOf(':');
     if (separator <= 0 || separator === value.length - 1)
         return null;
     return { type: value.slice(0, separator), id: value.slice(separator + 1) };
 }
+function parseMetadata(value) {
+    try {
+        const parsed = JSON.parse(value || '{}');
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.length > 0) : [];
+}
+function optionalMetadataString(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+function facetFromEdge(edge, projectId) {
+    return {
+        type: edge.target_type,
+        value: edge.target_id,
+        label: facetLabel(edge.target_type, edge.target_id),
+        nodeId: nodeId(edge.target_type, edge.target_id, projectId),
+        relation: edge.relation_type,
+    };
+}
+function facetLabel(type, value) {
+    if (type === 'topic')
+        return value.split('/').pop() || value;
+    if (type === 'issue') {
+        if (value === 'memory-context-blackbox')
+            return 'Memory Context 黑盒';
+        if (value === 'graph-runtime-blackbox')
+            return 'Graph Runtime 黑盒';
+        if (value === 'atlas-readability')
+            return 'Atlas 可读性黑盒';
+        if (value === 'auto-injection-mismatch')
+            return '自动注入不一致';
+    }
+    return value;
+}
+function intersectSets(sets) {
+    if (!sets.length)
+        return new Set();
+    const [first, ...rest] = sets;
+    const result = new Set();
+    for (const value of first ?? []) {
+        if (rest.every((set) => set.has(value)))
+            result.add(value);
+    }
+    return result;
+}
+function scoreCard(card) {
+    const issuePriority = card.issueType === 'memory-context-blackbox' ? 4
+        : card.issueType === 'graph-runtime-blackbox' ? 2
+            : card.issueType === 'atlas-readability' ? 1
+                : 0;
+    return card.matchedFacets.length * 10 + issuePriority + card.matchedPaths.reduce((sum, path) => sum + path.confidence, 0) + (card.localDate ? 0.1 : 0);
+}
+function mergeRelatedCards(...groups) {
+    const merged = new Map();
+    for (const group of groups)
+        for (const card of group)
+            if (!merged.has(card.canonicalId))
+                merged.set(card.canonicalId, card);
+    return Array.from(merged.values());
+}

package/dist/types/index.d.ts

@@ -850,6 +850,9 @@ export interface EventAuditPage {
         sessionId?: string[];
         startTime?: number;
         endTime?: number;
+        sinceGlobalSeq?: number;
+        untilGlobalSeq?: number;
+        order?: 'asc' | 'desc';
     };
 }
 //# sourceMappingURL=index.d.ts.map

package/examples/hermes-backend/AGENTS.md

@@ -122,12 +122,14 @@ cogmem normalize-transcript --input ./hermes-sessions.jsonl --output ./hermes.no
 cogmem import-hermes --workspace . --project hermes --session ./hermes.normalized.md
 ```
 
-Cogmem 3.6.4 skips import batch sealing for empty episode boundaries and skips legacy empty Dream jobs so one bad imported episode cannot block the queue.
+Cogmem skips import batch sealing for empty episode boundaries and skips legacy empty Dream jobs so one bad imported episode cannot block the queue.
 
 After import, use this order:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
+cogmem memory candidates --project hermes --json
 cogmem episode status --project hermes --json
 cogmem dream status --project hermes --json
 cogmem dream tick --project hermes --mode auto --max-episodes 20 --json
@@ -135,9 +137,10 @@ cogmem memory candidates --project hermes --status candidate --json
 cogmem memory govern --project hermes --limit 100 --json
 cogmem memory candidates --project hermes --status needs_confirmation --json
 cogmem memory review --project hermes --id <candidate-id> --action approve --actor <operator> --reason "confirmed by user" --confirmation-event <user-event-id> --json
+cogmem memory recall --query "<verification question>" --project hermes --agent hermes --json
 ```
 
-`needs_confirmation` is not the Dream backlog. `memory govern` does not approve it; use `memory review` with explicit evidence.
+`memory plan` is the first agent-safe health and next-action command. Only run `dream_tick` when it appears in `nextActions`; if `nonBlocking` contains `raw_dream_ledger_lag` with `resolvableByDreamTick:false`, inspect raw sources or episode/import boundaries instead of retrying `dream tick`. Default `memory candidates --json` groups ordinary, `needs_confirmation`, and deferred review queues; use `--status` only when a human asks for one queue. `needs_confirmation` is not the Dream backlog. `memory govern` does not approve it; use `memory review` with explicit evidence.
 
 ## Active Memory Search
 
@@ -153,15 +156,18 @@ For inventory or product questions, use recall first and raw search as a forensi
 cogmem memory recall --query "我们记录过哪些库存" --project hermes --agent hermes --json
 cogmem memory search --query "エルビ 库存" --project hermes --json
 cogmem memory show --event <event-id> --before 2 --after 2 --json
+cogmem memory recall --query "几个月前我们是不是讨论过 Cogmem 的记忆黑盒" --intent historical_discussion --project hermes --agent hermes --json
+cogmem memory list --project hermes --since <globalSeq> --order asc --json
 ```
 
 `vectors: 0` does not mean Cogmem has no memory. It means the dense vector index has no hot vectors yet. `memory recall` still falls back to governed raw ledger search and returns `sourceContext` locators. Broad inventory questions are expanded into structured cues such as `库存管理`, `在库`, `产品コード`, and `数量`; if compiled-memory candidates miss those cues, raw ledger evidence is preferred.
 
-`sourceContext` and `memory show --json` now share the same replay contract: each event has a `label`, optional `charRange` / `sourceRange`, and `sourceContext.window` / `window` metadata with requested counts, actual counts, `excludesAnchor`, `ordering`, `roleFilter`, and `overlapHandling`. Use those fields before quoting exact wording or explaining what happened before/after a recalled point.
+`sourceContext` and `memory show --json` share the same replay contract: each event has a `label`, optional `charRange` / `sourceRange`, and `sourceContext.window` / `window` metadata with requested counts, actual counts, `excludesAnchor`, `ordering`, `roleFilter`, and `overlapHandling`. Use those fields before quoting exact wording or explaining what happened before/after a recalled point. Raw Ledger list rows and Atlas search/explore evidence include `sourceLocator.command` and `sourceLocator.contextCommand`; run those commands before saying the source event is unavailable.
 
 Check status with:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
 ```
 
@@ -221,12 +227,12 @@ Hermes has no automatic observation path in this integration. Use `cogmem_episod
 
 Use `cogmem_topic_operate` with actor `user_explicit` only for explicit user naming/organization instructions. Model suggestions use `model_candidate` and remain reviewable; alias collisions fail closed. Use `cogmem_episode_repair` for split/merge/move/reclassify/requeue work so receipts, stale candidates, cross-references, Dream jobs, and audit records stay synchronized. Do not hand-edit the database.
 
-Use `cogmem memory map --project hermes --json` or MCP `cogmem_memory_map` to inspect Memory Binding and Graph Recall counters. Bindings attach high-value user raw events to stable topic/entity paths, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down only; they are not verified facts, user preferences, or instructions. Correction bindings expose review flags and correction edges. If `cogmem memory tick --project hermes --json` suggests `bind_raw_events`, run `cogmem memory bind --project hermes --json`. Re-run `cogmem connect hermes --workspace . --auto` after upgrades to patch existing MCP allow-lists with new Cogmem tools.
+Use `cogmem memory map --project hermes --json` or MCP `cogmem_memory_map` to inspect Memory Binding and Graph Recall counters. Bindings attach high-value user raw events to stable topic/entity paths, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down only; they are not verified facts, user preferences, or instructions. Correction bindings expose review flags and correction edges. If `cogmem memory tick --project hermes --json` suggests `bind_raw_events`, run `cogmem memory bind --project hermes --json`; it scans the historical ledger by cursor and can resume with `--since <globalSeq>`. For old-discussion questions, use `cogmem memory recall --intent historical_discussion ...` or `cogmem_graph_explore`; in 3.7.0 cards carry `canonicalId`, `matchedFacets`, `matchedPaths`, `relatedButNotSelected`, and `sourceLocator`. Answer from the selected canonical card, not from a side card. Re-run `cogmem connect hermes --workspace . --auto --force --json` after upgrades to patch existing MCP allow-lists with new Cogmem tools. Follow only `nextCommands` for unattended agent work; operator/host actions are in `nextSteps` with `safeForAutomation=false`.
 
 Dream correction records require explicit user clarification; assistant self-correction and questions containing `是不是` are not user-owned contradictions. Invalid provider output is a rejected diagnostic. Maintenance ticks supersede `needs_confirmation` entries older than the default 30-day TTL and retain their evidence rows.
 
 ## Memory Atlas navigation
 
-For broad inventory or historical questions call `cogmem_graph_explore`. Use `cogmem_graph_search` and `cogmem_graph_node` for known concepts, `cogmem_graph_neighbors`/`cogmem_graph_path` for relations, and `cogmem_graph_timeline` for ordered reconstruction. Use `cogmem_recall` for a direct fact and follow event IDs to `cogmem memory show` for exact wording.
+For broad inventory or historical questions call `cogmem_graph_explore`. Use `cogmem_graph_search` and `cogmem_graph_node` for known concepts, `cogmem_graph_neighbors`/`cogmem_graph_path` for relations, and `cogmem_graph_timeline` for ordered reconstruction. Use `cogmem_recall` for a direct fact and follow event IDs or returned `sourceLocator` commands to `cogmem memory show` for exact wording.
 
 Combine the filters present in the user's message, including project, time, topic, entity/target, memory kind, and ordinary cues. Do not force an entity + time + action tuple. A cold result is newly visible, not newly verified or promoted.

package/examples/hermes-backend/README.md

@@ -75,7 +75,9 @@ cogmem import-hermes --workspace . --project hermes
 After import:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
+cogmem memory candidates --project hermes --json
 cogmem episode status --project hermes --json
 cogmem dream status --project hermes --json
 cogmem dream tick --project hermes --mode auto --max-episodes 20 --json
@@ -101,13 +103,13 @@ cogmem import-hermes --workspace . --project hermes --session ./one.md --session
 The import command is idempotent. Re-running it against the same database skips records already processed by the cursor store. Imported raw records enter the same Episode Assembler used by live turns and are sealed at the explicit import batch boundary.
 Imported records are embedded through the configured kernel embedder during import.
 
-MCP recall JSON includes `decisionTrace`. Check its selected lane, reason, and candidate counts before concluding that a memory is absent, and use `sourceContext.locator.command` for exact wording. Raw text fallback searches the fully scoped ledger and prefers original user anchors over later assistant retellings when cue scores tie.
+MCP recall JSON includes `decisionTrace`. Check its selected lane, reason, and candidate counts before concluding that a memory is absent, and use `sourceContext.locator.command` for exact wording. Raw text fallback searches the fully scoped ledger and prefers original user anchors over later assistant retellings when cue scores tie. For old-discussion questions, run `cogmem memory recall --query "<past discussion>" --intent historical_discussion --project hermes --agent hermes --json`, then follow `sourceLocator` or inspect `cogmem memory list --project hermes --since <globalSeq> --order asc --json`.
 
 Dream stores explicit user clarification as organizational correction evidence rather than an automatic contradiction. Assistant self-correction and negative-form questions do not create user-owned corrections. Resolve `needs_confirmation` with `cogmem_candidate_review` or `cogmem memory review`; maintenance only supersedes entries left stale past the default 30-day TTL.
 
-After upgrades, reload MCP. Rerun `cogmem connect hermes --workspace . --auto --force` when MCP wiring, allow-listed tools, or the installed skill bundle changed.
+After upgrades, reload MCP. Rerun `cogmem connect hermes --workspace . --auto --force --json` when MCP wiring, allow-listed tools, or the installed skill bundle changed. Follow only JSON `nextCommands` for unattended agent work; operator/host actions are in `nextSteps` with `safeForAutomation=false`.
 
-Cogmem 3.6.4 exposes seven read-only/idempotent Memory Atlas query tools plus explicit `cogmem_graph_touch`, installs from npm by default, and prevents empty imported episodes from blocking Dream. Use explore for broad memory inventory/history, search and node for a known concept, path/neighbors for relations, timeline for ordered reconstruction, and normal recall for a direct fact. Query facets combine the user's actual project, time, topic, entity/target, memory-kind, action, and keyword conditions like table filters, so cold memory can be revived without requiring an entity-time-action tuple. Touch only nodes actually used, and follow returned event IDs to raw evidence before quoting exact wording.
+Cogmem 3.7.0 exposes read-only/idempotent Memory Atlas query tools plus explicit `cogmem_graph_touch`, installs from npm by default, prevents empty imported episodes from blocking Dream, and adds an agent-safe operations protocol. Use `memory plan` for the next safe command, grouped `memory candidates --json` for queue state, `historical_discussion` recall for old-discussion questions, and returned `sourceLocator` commands for exact evidence. Only run `dream_tick` when it appears in `memory plan.nextActions`; `raw_dream_ledger_lag` in `nonBlocking` has `resolvableByDreamTick:false` and is not fixed by looping `dream tick`. Use explore for broad memory inventory/history, search and node for a known concept, path/neighbors for relations, timeline for ordered reconstruction, and normal recall for a direct fact. Query facets combine the user's actual project, day/month/year, topic, issue, entity/target, session/thread, memory-kind, action-kind, and keyword conditions like table filters, so cold memory can be revived without requiring an entity-time-action tuple. Prefer returned `cards[]` for historical discussion: `canonicalId` dedupes the episode, `matchedFacets` explains why it matched, `relatedButNotSelected` is only side context, and `sourceLocator` opens raw evidence. Touch only nodes actually used, and follow returned event IDs or `sourceLocator` commands before quoting exact wording.
 
 ## Runtime
 

package/examples/hermes-backend/SKILL.md

@@ -114,7 +114,7 @@ timeout_ms = 60000
 
 ## Migrate Existing Hermes Memory
 
-Upgrade a 3.5.2 database, an existing 3.6.0 database, or a pre-release schema-25 test database to schema 27 in one backed-up command:
+Upgrade a 3.5.2 database, an existing 3.6.x database, or a pre-release schema-25 test database to the current 3.7.0 schema/projection set in one backed-up command:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -180,12 +180,14 @@ cogmem import-hermes --workspace . --project hermes --session ./hermes.normalize
 
 The importer is idempotent. Re-running it skips records already imported into the same memory database.
 
-Cogmem 3.6.4 skips import batch sealing for empty episode boundaries and Dream skips legacy empty episode jobs instead of blocking the whole queue. If `episode status` shows `dreamError` beginning with `episode_empty`, inspect the source events and use episode repair instead of editing SQLite rows.
+Cogmem skips import batch sealing for empty episode boundaries and Dream skips legacy empty episode jobs instead of blocking the whole queue. If `episode status` shows `dreamError` beginning with `episode_empty`, inspect the source events and use episode repair instead of editing SQLite rows.
 
 Run the maintenance loop under host supervision after import and during normal use. `needs_confirmation` is a human review queue, not the Dream backlog, and `memory govern` promotes only ordinary `candidate` rows:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
+cogmem memory candidates --project hermes --json
 cogmem episode status --project hermes --json
 cogmem dream status --project hermes --json
 cogmem dream tick --project hermes --mode auto --max-episodes 20 --json
@@ -196,6 +198,8 @@ cogmem memory review --project hermes --id <candidate-id> --action approve --act
 cogmem memory recall --query "<verification question>" --project hermes --agent hermes --json
 ```
 
+`memory plan` is the first agent-safe health and next-action command. It explains which queues block release, which work is non-blocking, whether vectors are empty but fallback recall is available, and what command should run next. Only run `dream_tick` when it appears in `nextActions`; if `nonBlocking` contains `raw_dream_ledger_lag` with `resolvableByDreamTick:false`, inspect raw sources or episode/import boundaries instead of retrying `dream tick`. Default `memory candidates --json` groups ordinary candidates, `needs_confirmation`, and deferred review entries; use `--status` only when the operator asks for one queue.
+
 A host timer may run this bounded tick periodically. The tick exits after inspecting the backlog and performs no work when no sealed episode is ready.
 
 ## Active Memory Search
@@ -210,7 +214,9 @@ Choose the graph tool from the question shape:
 - Direct factual question: `cogmem_recall`.
 - Exact wording: follow an event ID with `cogmem memory show`.
 
-Atlas combines whatever conditions the user supplies like table filters. Do not require entity + time + action. Project, time, topic, entity/target, memory kind, and ordinary cues may revive cold nodes together. Activation is visibility, not truth. Atlas summaries are hints and never replace raw evidence.
+Atlas combines whatever conditions the user supplies like table filters. Do not require entity + time + action. Project, day/month/year, topic, issue, entity/target, session/thread, memory kind, action kind, and ordinary cues may revive cold nodes together. Activation is visibility, not truth. Atlas summaries are hints and never replace raw evidence.
+
+In 3.7.0, `cogmem_graph_search`, `cogmem_graph_explore`, and historical recall can return canonical `cards[]`. Prefer cards over raw node labels for past-discussion questions. A card's `canonicalId` is the single episode identity; `matchedFacets` explains time/topic/issue/entity matches; `matchedPaths` explains how the card was reached; `relatedButNotSelected` is context only and must not replace the selected answer; `sourceLocator.command` is the command to inspect exact original text. If `relaxationTrace` exists, say the answer is a relaxed nearby match, not an exact hit.
 
 When the prompt does not contain enough injected Cogmem context, do not search legacy memory files first. Ask Cogmem directly:
 
@@ -233,9 +239,25 @@ cogmem memory show --event <event-id> --before 2 --after 2 --json
 
 `sourceContext` entries include stable `label` values, optional `charRange` / `sourceRange`, and `sourceContext.window` metadata. Use `window.before.requestedCount`, `window.before.count`, `window.after.requestedCount`, `window.after.count`, `excludesAnchor`, `ordering`, `roleFilter`, and `overlapHandling` to understand the before/after replay. `memory show --json` returns the same contract, so the labels in MCP recall can be matched to the local CLI output.
 
+For “did we discuss this before?”, “几个月前是不是聊过…”, “记忆黑盒”, MCP memory gaps, or other old-discussion questions, force the historical-discussion lane before saying memory is absent:
+
+```bash
+cogmem memory recall --query "<past discussion question>" --intent historical_discussion --project hermes --agent hermes --json
+```
+
+If the answer depends on exact wording or nearby context, run the returned `sourceLocator` or use a Raw Ledger cursor:
+
+```bash
+cogmem memory show --event <eventId> --project hermes --before 2 --after 2 --json
+cogmem memory list --project hermes --since <globalSeq> --order asc --json
+```
+
+Raw list rows and Atlas search/explore evidence include `sourceLocator.command` and a deeper `sourceLocator.contextCommand`. Use those commands before claiming an event ID is missing, before quoting exact words, or before treating an Atlas summary as the source.
+
 `vectors: 0` does not mean memory is unavailable. It means dense vector search has no hot index yet; `memory recall` still has governed raw-ledger fallback. Broad inventory questions are expanded into structured cues such as `库存管理`, `在库`, `产品コード`, and `数量`; when compiled candidates miss those cues, prefer the raw ledger result and use its `sourceContext` for details. Check status with:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
 ```
 
@@ -252,12 +274,13 @@ Default recall includes untagged and `collection:anchor` memory only. Ask for `c
 For host upkeep, inspect the self-map and run an explicit tick:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory map --project hermes --json
 cogmem memory tick --project hermes --json
 cogmem memory bind --project hermes --json
 ```
 
-`memory tick` does not start a daemon. Use its `suggestedActions` to decide whether Hermes should run `dream tick`, `memory govern`, `episode repair`, entity review, re-embedding, or `memory bind` for unbound high-value raw events.
+`memory tick` does not start a daemon. Use its `suggestedActions` to decide whether Hermes should run `dream tick`, `memory govern`, `episode repair`, entity review, re-embedding, or `memory bind` for unbound high-value raw events. `undreamedRawCount` by itself is Raw Ledger coverage lag, not a sealed-episode job; do not loop `dream tick` unless `memory plan.nextActions` contains `dream_tick`. `memory bind` scans the historical Raw Ledger by cursor instead of only the latest page; resume large repairs with `--since <globalSeq>`.
 
 `memory map` also exposes Memory Binding and Graph Recall counters. Bindings connect high-value user raw events to stable topic/entity paths before promotion, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down. Correction bindings expose review flags and correction edges. Use graph recall hits for source drill-down and topic continuity only; do not treat bindings, clusters, or edges as verified facts, user preferences, or prompt instructions.
 
@@ -267,7 +290,7 @@ Explicit user clarification is organizational correction evidence, not an automa
 
 When importing OpenClaw-style session Markdown into a Hermes project, Cogmem accepts multiline bodies below empty role headers, collapses only adjacent exact export duplicates, and uses `# Session: ... UTC` as the chronological timestamp base rather than file mtime.
 
-After upgrading, rerun `cogmem connect hermes --workspace . --auto --force` and reload MCP so existing allow-lists and skill instructions receive the current tools and contracts.
+After upgrading, rerun `cogmem connect hermes --workspace . --auto --force --json` and reload MCP so existing allow-lists and skill instructions receive the current tools and contracts. In JSON output, follow only `nextCommands` for unattended agent work; unsafe operator or host steps such as interactive init and `/reload-mcp` are listed under `nextSteps` with `safeForAutomation=false`.
 
 ## Runtime Wiring