cogmem 3.7.1 → 3.7.3

package/dist/store/EventStore.js

@@ -3,7 +3,7 @@ import { createHash, randomUUID } from 'crypto';
 const MEMORY_EVENT_COLUMNS = `
   event_id, global_seq, stream_id, stream_type, event_type, raw_event_type, event_version, project_id,
   workspace_id, actor_id, causation_id, correlation_id, source_neuron_id, source_id,
-  content_hash, thread_id, session_id, local_date, thread_seq, turn_id, turn_seq,
+  content_hash, thread_id, session_id, local_date, local_date_source, thread_seq, turn_id, turn_seq,
   event_ordinal, role, parent_event_id, prev_event_id, next_event_id, causality_type,
   source_offset, line_start, line_end, char_start, char_end, ordering_confidence,
   occurred_at, payload_json, payload_hash, created_at
@@ -11,9 +11,16 @@ const MEMORY_EVENT_COLUMNS = `
 export class EventStore {
     encryptionProvider;
     db;
+    ownsDb = true;
     constructor(dbPath = ':memory:', encryptionProvider) {
         this.encryptionProvider = encryptionProvider;
-        this.db = new Database(dbPath);
+        if (dbPath instanceof Database) {
+            this.db = dbPath;
+            this.ownsDb = false;
+        }
+        else {
+            this.db = new Database(dbPath);
+        }
         this.initializeSchema();
     }
     initializeSchema() {
@@ -37,6 +44,7 @@ export class EventStore {
         thread_id TEXT,
         session_id TEXT,
         local_date TEXT,
+        local_date_source TEXT NOT NULL DEFAULT 'legacy_unknown',
         thread_seq INTEGER,
         turn_id TEXT,
         turn_seq INTEGER,
@@ -115,6 +123,7 @@ export class EventStore {
         addColumn('thread_id', 'thread_id TEXT');
         addColumn('session_id', 'session_id TEXT');
         addColumn('local_date', 'local_date TEXT');
+        addColumn('local_date_source', "local_date_source TEXT NOT NULL DEFAULT 'legacy_unknown'");
         addColumn('thread_seq', 'thread_seq INTEGER');
         addColumn('turn_id', 'turn_id TEXT');
         addColumn('turn_seq', 'turn_seq INTEGER');
@@ -134,6 +143,17 @@ export class EventStore {
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_memory_events_thread_order ON memory_events(thread_id, thread_seq, event_ordinal, global_seq);`);
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_memory_events_parent ON memory_events(parent_event_id);`);
         this.db.exec(`
+      CREATE TABLE IF NOT EXISTS import_source_anchors (
+        project_id TEXT NOT NULL,
+        source_id TEXT NOT NULL,
+        import_anchor TEXT NOT NULL,
+        event_id TEXT NOT NULL UNIQUE,
+        content_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (project_id, source_id, import_anchor)
+      );
+    `);
+        this.db.exec(`
       CREATE VIRTUAL TABLE IF NOT EXISTS memory_events_fts USING fts5(
         event_id UNINDEXED,
         text,
@@ -149,9 +169,11 @@ export class EventStore {
     `);
         this.rebuildRawEventFtsIfNeeded();
     }
-    append(input) {
+    append(input, retry = 0) {
         const eventVersion = input.eventVersion ?? this.getNextEventVersion(input.streamId);
         const occurredAt = input.occurredAt ?? Date.now();
+        if (!Number.isFinite(occurredAt) || Math.abs(occurredAt) > 8_640_000_000_000_000)
+            throw new Error('invalid_event_timestamp');
         const payloadJson = JSON.stringify(input.payload);
         const storedPayloadJson = this.encodePayload(payloadJson);
         const payloadHash = createHash('sha256').update(payloadJson).digest('hex');
@@ -159,6 +181,14 @@ export class EventStore {
         const threadSeq = input.threadSeq ?? (threadId ? this.getNextThreadSeq(threadId) : undefined);
         const globalSeq = this.getNextGlobalSeq();
         const createdAt = Date.now();
+        const localDateSource = input.localDateSource ?? (input.localDate ? 'explicit' : 'generated_utc');
+        if (localDateSource !== 'explicit' && localDateSource !== 'generated_utc' && localDateSource !== 'legacy_unknown')
+            throw new Error('invalid_local_date_source');
+        if (localDateSource === 'explicit' && !input.localDate)
+            throw new Error('explicit_local_date_required');
+        const generatedUtcDate = new Date(occurredAt).toISOString().slice(0, 10);
+        if (localDateSource === 'generated_utc' && input.localDate && input.localDate !== generatedUtcDate)
+            throw new Error('generated_utc_local_date_mismatch');
         const event = {
             eventId: input.eventId || `evt-${randomUUID()}`,
             globalSeq,
@@ -178,6 +208,7 @@ export class EventStore {
             threadId,
             sessionId: input.sessionId,
             localDate: input.localDate ?? new Date(occurredAt).toISOString().slice(0, 10),
+            localDateSource,
             threadSeq,
             turnId: input.turnId,
             turnSeq: input.turnSeq,
@@ -192,25 +223,80 @@ export class EventStore {
             lineEnd: input.lineEnd,
             charStart: input.charStart,
             charEnd: input.charEnd,
-            orderingConfidence: input.orderingConfidence ?? (threadSeq || input.eventOrdinal ? 'high' : 'low'),
+            orderingConfidence: input.orderingConfidence ?? (threadSeq !== undefined || input.eventOrdinal !== undefined || input.sourceOffset !== undefined || input.lineStart !== undefined ? 'high' : 'low'),
             occurredAt,
             payload: input.payload,
             payloadHash,
             createdAt,
             ingestedAt: createdAt
         };
-        this.db.prepare(`
+        const insert = () => this.db.prepare(`
       INSERT INTO memory_events (
         event_id, global_seq, stream_id, stream_type, event_type, raw_event_type, event_version, project_id,
         workspace_id, actor_id, causation_id, correlation_id, source_neuron_id, source_id,
-        content_hash, thread_id, session_id, local_date, thread_seq, turn_id, turn_seq,
+        content_hash, thread_id, session_id, local_date, local_date_source, thread_seq, turn_id, turn_seq,
         event_ordinal, role, parent_event_id, prev_event_id, next_event_id, causality_type,
         source_offset, line_start, line_end, char_start, char_end, ordering_confidence,
         occurred_at, payload_json, payload_hash, created_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(event.eventId, event.globalSeq ?? null, event.streamId, event.streamType, event.eventType, event.rawEventType || null, event.eventVersion, event.projectId || null, event.workspaceId || null, event.actorId || null, event.causationId || null, event.correlationId || null, event.sourceNeuronId || null, event.sourceId || null, event.contentHash || null, event.threadId || null, event.sessionId || null, event.localDate || null, event.threadSeq || null, event.turnId || null, event.turnSeq || null, event.eventOrdinal || null, event.role || null, event.parentEventId || null, event.prevEventId || null, event.nextEventId || null, event.causalityType || null, event.sourceOffset || null, event.lineStart || null, event.lineEnd || null, event.charStart || null, event.charEnd || null, event.orderingConfidence || null, event.occurredAt, storedPayloadJson, event.payloadHash, event.createdAt);
-        this.upsertRawEventFts(event);
-        return event;
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(event.eventId, event.globalSeq ?? null, event.streamId, event.streamType, event.eventType, event.rawEventType || null, event.eventVersion, event.projectId || null, event.workspaceId || null, event.actorId || null, event.causationId || null, event.correlationId || null, event.sourceNeuronId || null, event.sourceId || null, event.contentHash || null, event.threadId || null, event.sessionId || null, event.localDate || null, event.localDateSource || 'legacy_unknown', event.threadSeq ?? null, event.turnId || null, event.turnSeq ?? null, event.eventOrdinal ?? null, event.role || null, event.parentEventId || null, event.prevEventId || null, event.nextEventId || null, event.causalityType || null, event.sourceOffset ?? null, event.lineStart ?? null, event.lineEnd ?? null, event.charStart ?? null, event.charEnd ?? null, event.orderingConfidence || null, event.occurredAt, storedPayloadJson, event.payloadHash, event.createdAt);
+        try {
+            this.db.transaction(() => {
+                insert();
+                this.upsertImportAnchor(event);
+                this.upsertRawEventFts(event);
+            })();
+            return event;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const streamConflict = /UNIQUE constraint failed: memory_events\.(stream_id|global_seq)/.test(message);
+            const anchorConflict = message === 'import_anchor_already_exists';
+            const autoEventVersion = input.eventVersion === undefined;
+            const autoThreadSeq = input.threadSeq === undefined;
+            if ((streamConflict || message.includes('database is locked')) && autoEventVersion && retry < 5) {
+                return this.append({ ...input, eventVersion: undefined, threadSeq: autoThreadSeq ? undefined : input.threadSeq }, retry + 1);
+            }
+            if (!anchorConflict)
+                throw error;
+            const metadata = event.payload?.metadata;
+            const anchor = typeof metadata?.importAnchor === 'string' ? metadata.importAnchor : undefined;
+            const existing = anchor && event.projectId && event.sourceId
+                ? this.findImportedEventAnchor(event.projectId, event.sourceId, anchor)
+                : null;
+            if (!existing)
+                throw error;
+            if (existing.contentHash !== event.contentHash)
+                throw new Error(`import_anchor_content_conflict:${anchor}`);
+            return existing;
+        }
+    }
+    upsertImportAnchor(event) {
+        const metadata = event.payload?.metadata;
+        const anchor = typeof metadata?.importAnchor === 'string' ? metadata.importAnchor : undefined;
+        if (!anchor || !event.projectId || !event.sourceId || !event.contentHash)
+            return;
+        this.db.prepare(`
+      INSERT INTO import_source_anchors (project_id, source_id, import_anchor, event_id, content_hash, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_id, source_id, import_anchor) DO NOTHING
+    `).run(event.projectId, event.sourceId, anchor, event.eventId, event.contentHash, event.createdAt);
+        const inserted = this.db.prepare(`SELECT event_id FROM import_source_anchors WHERE project_id = ? AND source_id = ? AND import_anchor = ?`)
+            .get(event.projectId, event.sourceId, anchor);
+        if (inserted?.event_id !== event.eventId) {
+            const existingEvent = inserted?.event_id
+                ? this.db.prepare(`SELECT 1 FROM memory_events WHERE event_id = ?`).get(inserted.event_id)
+                : null;
+            if (!existingEvent) {
+                this.db.prepare(`
+          UPDATE import_source_anchors
+          SET event_id = ?, content_hash = ?, created_at = ?
+          WHERE project_id = ? AND source_id = ? AND import_anchor = ?
+        `).run(event.eventId, event.contentHash, event.createdAt, event.projectId, event.sourceId, anchor);
+                return;
+            }
+            throw new Error('import_anchor_already_exists');
+        }
     }
     getNextGlobalSeq() {
         const row = this.db.prepare(`
@@ -249,9 +335,18 @@ export class EventStore {
       FROM memory_events
       WHERE (? IS NULL OR occurred_at > ?)
       ORDER BY COALESCE(global_seq, 0) ASC, occurred_at ASC, event_id ASC
-    `).all(lastEventTime || null, lastEventTime || null);
+    `).all(lastEventTime ?? null, lastEventTime ?? null);
         return rows.map((row) => this.mapRow(row));
     }
+    findImportedEventAnchor(projectId, sourceId, importAnchor) {
+        const row = this.db.prepare(`
+      SELECT ${qualifiedMemoryEventColumns('e')}
+      FROM import_source_anchors a
+      JOIN memory_events e ON e.event_id = a.event_id
+      WHERE a.project_id = ? AND a.source_id = ? AND a.import_anchor = ?
+    `).get(projectId, sourceId, importAnchor);
+        return row ? this.mapRow(row) : null;
+    }
     getLatestEvent() {
         const row = this.db.prepare(`
       SELECT ${MEMORY_EVENT_COLUMNS}
@@ -430,9 +525,10 @@ export class EventStore {
             conditions.push('local_date = ?');
             params.push(options.localDate);
         }
-        const limitSql = options.limit ? 'LIMIT ?' : '';
-        if (options.limit)
-            params.push(options.limit);
+        const boundedLimit = options.limit === undefined ? undefined : Math.max(1, Math.min(Math.trunc(options.limit), 10_000));
+        const limitSql = boundedLimit === undefined ? '' : 'LIMIT ?';
+        if (boundedLimit !== undefined)
+            params.push(boundedLimit);
         const rows = this.db.prepare(`
       SELECT ${MEMORY_EVENT_COLUMNS}
       FROM memory_events
@@ -564,7 +660,8 @@ export class EventStore {
     `).run(checkpoint.projectionName, checkpoint.lastEventId || null, checkpoint.lastEventTime || null, checkpoint.lastRebuildAt || null, checkpoint.lastFullCount, checkpoint.lastChecksum || null, checkpoint.status, checkpoint.metadata ? JSON.stringify(checkpoint.metadata) : null);
     }
     close() {
-        this.db.close();
+        if (this.ownsDb)
+            this.db.close();
     }
     mapRow(row) {
         return {
@@ -586,20 +683,21 @@ export class EventStore {
             threadId: row.thread_id || (row.stream_type === 'thread' ? row.stream_id : undefined),
             sessionId: row.session_id || undefined,
             localDate: row.local_date || undefined,
-            threadSeq: row.thread_seq || undefined,
+            localDateSource: row.local_date_source || legacyLocalDateSource(row.payload_json),
+            threadSeq: row.thread_seq ?? undefined,
             turnId: row.turn_id || undefined,
-            turnSeq: row.turn_seq || undefined,
-            eventOrdinal: row.event_ordinal || undefined,
+            turnSeq: row.turn_seq ?? undefined,
+            eventOrdinal: row.event_ordinal ?? undefined,
             role: row.role || undefined,
             parentEventId: row.parent_event_id || undefined,
             prevEventId: row.prev_event_id || undefined,
             nextEventId: row.next_event_id || undefined,
             causalityType: row.causality_type || undefined,
-            sourceOffset: row.source_offset || undefined,
-            lineStart: row.line_start || undefined,
-            lineEnd: row.line_end || undefined,
-            charStart: row.char_start || undefined,
-            charEnd: row.char_end || undefined,
+            sourceOffset: row.source_offset ?? undefined,
+            lineStart: row.line_start ?? undefined,
+            lineEnd: row.line_end ?? undefined,
+            charStart: row.char_start ?? undefined,
+            charEnd: row.char_end ?? undefined,
             orderingConfidence: row.ordering_confidence || undefined,
             occurredAt: row.occurred_at,
             payload: JSON.parse(this.decodePayload(row.payload_json)),
@@ -720,6 +818,29 @@ export class EventStore {
         return this.encryptionProvider?.decrypt(payloadJson) ?? payloadJson;
     }
 }
+function qualifiedMemoryEventColumns(alias) {
+    return MEMORY_EVENT_COLUMNS.split(',').map((column) => `${alias}.${column.trim()}`).join(', ');
+}
 function escapeSqlLike(value) {
     return value.replace(/[\\%_]/g, (character) => `\\${character}`);
 }
+function validCalendarDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/u.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+function legacyLocalDateSource(payloadJson) {
+    try {
+        const payload = JSON.parse(payloadJson);
+        if (payload.metadata?.localDateSource === 'event_store_utc_default')
+            return 'generated_utc';
+        if (payload.metadata?.localDateSource === 'explicit')
+            return 'explicit';
+    }
+    catch {
+        return 'legacy_unknown';
+    }
+    return 'legacy_unknown';
+}

package/dist/store/FactStore.js

@@ -122,7 +122,7 @@ export class FactStore {
         const rows = this.db.prepare(`
       SELECT *
       FROM facts
-      WHERE neuron_id IN (${placeholders})
+      WHERE neuron_id IN (${placeholders}) AND status IN ('provisional', 'provisional_enriched', 'verified')
       ORDER BY valid_from DESC, fact_id DESC
       LIMIT ?
     `).all(...neuronIds, limit);
@@ -139,14 +139,15 @@ export class FactStore {
           SELECT *
           FROM facts
           WHERE entity_id IN (${entityPlaceholders})
+            AND status IN ('provisional', 'provisional_enriched', 'verified')
             AND predicate_family IN (${predicateFamilies.map(() => '?').join(', ')})
           ORDER BY valid_from DESC, fact_id DESC
           LIMIT ?
         `).all(...entityIds, ...predicateFamilies, limit)
             : this.db.prepare(`
-          SELECT *
-          FROM facts
-          WHERE entity_id IN (${entityPlaceholders})
+      SELECT *
+      FROM facts
+      WHERE entity_id IN (${entityPlaceholders}) AND status IN ('provisional', 'provisional_enriched', 'verified')
           ORDER BY valid_from DESC, fact_id DESC
           LIMIT ?
         `).all(...entityIds, limit);
@@ -159,7 +160,7 @@ export class FactStore {
         const rows = this.db.prepare(`
       SELECT DISTINCT neuron_id
       FROM facts
-      WHERE entity_id IN (${placeholders})
+      WHERE entity_id IN (${placeholders}) AND status IN ('provisional', 'provisional_enriched', 'verified')
       ORDER BY valid_from DESC
       LIMIT ?
     `).all(...entityIds, limit);

package/dist/store/MemoryAtlasStore.d.ts

@@ -33,6 +33,7 @@ export declare class MemoryAtlasStore {
     evidenceTotal(nodeId: string, projectId: string): number;
     listEdges(projectId: string): MemoryAtlasEdge[];
     listEdgesForNodes(projectId: string, nodeIds: string[], limit?: number): MemoryAtlasEdge[];
+    listEdgesWithinNodes(projectId: string, nodeIds: string[], limit?: number): MemoryAtlasEdge[];
     findEdgesBetween(projectId: string, leftNodeId: string, rightNodeId: string): MemoryAtlasEdge[];
     findEdgesFromNodesToTarget(projectId: string, leftNodeIds: string[], rightNodeId: string): MemoryAtlasEdge[];
     listActions(projectId: string, options: {

package/dist/store/MemoryAtlasStore.js

@@ -301,6 +301,54 @@ export class MemoryAtlasStore {
             edges.push(...this.topicRelationEdges(projectId, topicPaths, Math.max(1, Math.min(limit, 2000))));
         return Array.from(new Map(edges.map((edge) => [`${edge.source}\0${edge.relation}\0${edge.target}`, edge])).values()).slice(0, Math.max(1, Math.min(limit, 4000)));
     }
+    listEdgesWithinNodes(projectId, nodeIds, limit = 4000) {
+        const selectedIds = new Set(Array.from(new Set(nodeIds)));
+        const parsed = Array.from(selectedIds).map((id) => parseNodeId(id, projectId)).filter((item) => Boolean(item));
+        if (!parsed.length)
+            return [];
+        const edges = [];
+        const cap = Math.max(1, Math.min(limit, 4000));
+        for (const sourceChunk of chunked(parsed, 120)) {
+            for (const targetChunk of chunked(parsed, 120)) {
+                const sourceClause = sourceChunk.map(() => '(source_type=? AND source_id=?)').join(' OR ');
+                const targetClause = targetChunk.map(() => '(target_type=? AND target_id=?)').join(' OR ');
+                const rows = this.db.prepare(`
+          SELECT * FROM memory_edges
+          WHERE project_id=? AND status IN ('active','weak')
+            AND (${sourceClause}) AND (${targetClause})
+          ORDER BY confidence DESC LIMIT ?
+        `).all(projectId, ...sourceChunk.flatMap((item) => [item.type, item.id]), ...targetChunk.flatMap((item) => [item.type, item.id]), cap);
+                for (const row of rows)
+                    edges.push({
+                        source: nodeId(String(row.source_type), String(row.source_id), projectId), relation: String(row.relation_type),
+                        target: nodeId(String(row.target_type), String(row.target_id), projectId), confidence: Number(row.confidence),
+                        evidenceEventIds: parseStringArray(String(row.evidence_event_ids_json || '[]')),
+                    });
+            }
+        }
+        const actionIds = parsed.filter((item) => item.type === 'action').map((item) => item.id);
+        if (actionIds.length) {
+            for (const chunk of chunked(actionIds, 400)) {
+                const actions = this.db.prepare(`SELECT action_id,target_entity_id,occurred_at,confidence FROM memory_action_frames
+          WHERE project_id=? AND action_id IN (${chunk.map(() => '?').join(',')})`).all(projectId, ...chunk);
+                for (const action of actions) {
+                    const evidenceEventIds = this.actionEvidenceIds(action.action_id, projectId);
+                    if (action.target_entity_id && selectedIds.has(`entity:${action.target_entity_id}`)) {
+                        edges.push({ source: `action:${action.action_id}`, relation: 'TARGETS', target: `entity:${action.target_entity_id}`, confidence: action.confidence, evidenceEventIds });
+                    }
+                    const timeId = timeNodeId(projectId, action.occurred_at);
+                    if (selectedIds.has(timeId))
+                        edges.push({ source: `action:${action.action_id}`, relation: 'OCCURRED_IN', target: timeId, confidence: 1, evidenceEventIds });
+                }
+            }
+        }
+        const topicPaths = parsed.filter((item) => item.type === 'topic').map((item) => item.id);
+        if (topicPaths.length) {
+            edges.push(...this.topicRelationEdges(projectId, topicPaths, cap)
+                .filter((edge) => selectedIds.has(edge.source) && selectedIds.has(edge.target)));
+        }
+        return Array.from(new Map(edges.map((edge) => [`${edge.source}\0${edge.relation}\0${edge.target}`, edge])).values());
+    }
     findEdgesBetween(projectId, leftNodeId, rightNodeId) {
         const left = parseNodeId(leftNodeId, projectId);
         const right = parseNodeId(rightNodeId, projectId);
@@ -725,6 +773,12 @@ function stringArray(value) {
 function optionalMetadataString(value) {
     return typeof value === 'string' && value ? value : undefined;
 }
+function chunked(values, size) {
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size)
+        chunks.push(values.slice(index, index + size));
+    return chunks;
+}
 function facetFromEdge(edge, projectId) {
     return {
         type: edge.target_type,

package/dist/types/ExtensionPoints.d.ts

@@ -106,9 +106,11 @@ export interface GraphEdgeRecordLike {
     status?: string;
 }
 export interface GraphEdgeStoreLike {
+    getDatabase(): import('bun:sqlite').default;
     list?(options?: unknown): GraphEdgeRecordLike[];
     listActiveNeighborEdges?(entityIds: string[], edgeTypes?: string[], limit?: number): GraphEdgeRecordLike[];
-    appendEdge?(input: unknown): GraphEdgeRecordLike;
+    appendEdge(input: unknown): GraphEdgeRecordLike;
+    invalidateEdge(edgeRecordId: string, metadata?: Record<string, unknown>): boolean;
 }
 export interface ProposalLedgerLike {
     append?(items: unknown[]): void;

package/dist/types/index.d.ts

@@ -277,6 +277,7 @@ export interface MemoryEvent<TPayload = Record<string, unknown>> {
     threadId?: string;
     sessionId?: string;
     localDate?: string;
+    localDateSource?: 'explicit' | 'generated_utc' | 'legacy_unknown';
     threadSeq?: number;
     turnId?: string;
     turnSeq?: number;

package/examples/hermes-backend/AGENTS.md

@@ -227,7 +227,7 @@ 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`; 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.1 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`.
+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.2 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.
 

package/examples/hermes-backend/README.md

@@ -109,7 +109,7 @@ Dream stores explicit user clarification as organizational correction evidence r
 
 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.7.1 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. Unicode entity cues are supported, but alias merges still require governed evidence. Prefer returned `cards[]` for historical discussion: `canonicalId` dedupes the episode, `matchedFacets` explains why it matched, `relatedButNotSelected` is only side context, `relaxationTrace` marks day/month/year or issue/topic fallback, and `sourceLocator` opens raw evidence. Touch only nodes actually used, and follow returned event IDs or `sourceLocator` commands before quoting exact wording.
+Cogmem 3.7.2 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. Unicode entity cues are supported, but alias merges still require governed evidence. Prefer returned `cards[]` for historical discussion: `canonicalId` dedupes the episode, `matchedFacets` explains why it matched, `relatedButNotSelected` is only side context, `relaxationTrace` marks day/month/year or issue/topic fallback, 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.x database, or a pre-release schema-25 test database to the current 3.7.1 schema/projection set 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.2 schema/projection set in one backed-up command:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -216,7 +216,7 @@ Choose the graph tool from the question shape:
 
 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. Entity cue extraction accepts Unicode letter/number names, but it is not full NER and must not be treated as proof that two aliases are the same person/tool. Activation is visibility, not truth. Atlas summaries are hints and never replace raw evidence.
 
-In 3.7.1, `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 match, not an exact hit; supported relaxations include day → month → year and issue → parent topic.
+In 3.7.2, `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 match, not an exact hit; supported relaxations include day → month → year and issue → parent topic.
 
 When the prompt does not contain enough injected Cogmem context, do not search legacy memory files first. Ask Cogmem directly:
 

package/examples/hermes-backend/references/operations.md

@@ -1,4 +1,4 @@
-# Cogmem 3.7.1 Operations Reference for Hermes
+# Cogmem 3.7.2 Operations Reference for Hermes
 
 Read this file when installing, upgrading, importing, repairing, or operating Cogmem. `SKILL.md` contains the decision rules; this file records the operational commands.
 
@@ -76,7 +76,7 @@ cogmem doctor
 cogmem connect hermes --workspace . --auto --force --json
 ```
 
-The backed-up command upgrades 3.5.2 schema 24, an existing 3.6.x database, or a pre-release schema-25 test database to the current 3.7.1 schema/projection state in one run and preserves Raw Ledger evidence. `--dry-run` is read-only and does not create `_schema_migrations`. Reload MCP after reconnecting.
+The backed-up command upgrades 3.5.2 schema 24, an existing 3.6.x database, or a pre-release schema-25 test database to the current 3.7.2 schema/projection state in one run and preserves Raw Ledger evidence. `--dry-run` is read-only and does not create `_schema_migrations`. Reload MCP after reconnecting.
 
 ## Import Hermes memory
 

package/examples/openclaw-backend/AGENTS.md

@@ -185,7 +185,7 @@ Recall behavior:
 - If `cogmem memory tick --project openclaw --json` suggests `bind_raw_events`, run `cogmem memory bind --project openclaw --json` to backfill imported or adapter-written raw user events into the binding graph.
 - For “did we discuss this before?”, “几个月前是不是聊过…”, “记忆黑盒”, or missing injection cases, run `cogmem memory recall --query "<past discussion question>" --intent historical_discussion --project openclaw --agent openclaw --json` before claiming no memory.
 - For ledger audits or resumable checks, use `cogmem memory list --project openclaw --since <globalSeq> --order asc --json`; list rows and Atlas search/explore evidence include `sourceLocator` commands.
-- For old-discussion or "do you remember" questions, prefer `cogmem memory recall --intent historical_discussion ...` or `cogmem memory graph-explore ... --json`. In 3.7.1, cards carry `canonicalId`, `matchedFacets`, `matchedPaths`, `relatedButNotSelected`, and `sourceLocator`; answer from the selected canonical card, not from a related-but-not-selected side card.
+- For old-discussion or "do you remember" questions, prefer `cogmem memory recall --intent historical_discussion ...` or `cogmem memory graph-explore ... --json`. In 3.7.2, cards carry `canonicalId`, `matchedFacets`, `matchedPaths`, `relatedButNotSelected`, and `sourceLocator`; answer from the selected canonical card, not from a related-but-not-selected side card.
 
 Installing the workspace skill makes the kernel procedure discoverable to OpenClaw agents. Installing the local auto wrapper makes future turns call the memory kernel automatically:
 

package/examples/openclaw-backend/README.md

@@ -84,7 +84,7 @@ cogmem memory tick --project openclaw --json
 cogmem memory bind --project openclaw --json
 ```
 
-Cogmem 3.7.1 keeps npm as the default install/update channel and upgrades Memory Atlas into a multi-dimensional navigation graph. 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`. The auto plugin uses one shared bridge/kernel lifecycle for graph exploration, evidence-bearing node/timeline drill-down, and recall, so OpenClaw does not need MCP for broad inventory/history questions. Atlas combines the query's actual project, day/month/year, topic, issue, entity/target, session/thread, memory-kind, action-kind, and keyword conditions like table filters; no fixed entity-time-action tuple is required. Unicode entity cues are supported, but alias merges still require governed evidence. Prefer returned `cards[]` for historical discussion: `canonicalId` dedupes the episode, `matchedFacets` explains why it matched, `relatedButNotSelected` is only side context, `relaxationTrace` marks day/month/year or issue/topic fallback, and `sourceLocator` opens the raw evidence.
+Cogmem 3.7.2 keeps npm as the default install/update channel and upgrades Memory Atlas into a multi-dimensional navigation graph. 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`. The auto plugin uses one shared bridge/kernel lifecycle for graph exploration, evidence-bearing node/timeline drill-down, and recall, so OpenClaw does not need MCP for broad inventory/history questions. Atlas combines the query's actual project, day/month/year, topic, issue, entity/target, session/thread, memory-kind, action-kind, and keyword conditions like table filters; no fixed entity-time-action tuple is required. Unicode entity cues are supported, but alias merges still require governed evidence. Prefer returned `cards[]` for historical discussion: `canonicalId` dedupes the episode, `matchedFacets` explains why it matched, `relatedButNotSelected` is only side context, `relaxationTrace` marks day/month/year or issue/topic fallback, and `sourceLocator` opens the raw evidence.
 
 ```bash
 cogmem memory plan --project openclaw --json

package/examples/openclaw-backend/SKILL.md

@@ -114,7 +114,7 @@ timeout_ms = 60000
 
 ## Migrate Existing OpenClaw Memory
 
-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.1 schema/projection set 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.2 schema/projection set in one backed-up command:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -282,7 +282,7 @@ Graph reads default to stale-safe diagnostics. If a drainer or gateway has SQLit
 
 Atlas combines the conditions present in the user's message like table filters. Do not force every question into entity + time + action. Project, day/month/year, topic, issue, entity/target, session/thread, memory kind, action kind, and ordinary cues may independently or jointly revive cold nodes. Entity cue extraction accepts Unicode letter/number names, but it is not full NER and must not be treated as proof that two aliases are the same person/tool. Graph reads do not change activation; explicitly touch only nodes the agent actually uses. Activation changes visibility only.
 
-In 3.7.1, `graph-search`, `graph-explore`, and historical recall can return `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 match, not an exact hit; supported relaxations include day → month → year and issue → parent topic.
+In 3.7.2, `graph-search`, `graph-explore`, and historical recall can return `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 match, not an exact hit; supported relaxations include day → month → year and issue → parent topic.
 
 Follow returned `sourceLocator.command` or event IDs with `cogmem memory show`; never treat an Atlas summary or title as evidence.
 

package/examples/openclaw-backend/references/operations.md

@@ -1,4 +1,4 @@
-# Cogmem 3.7.1 Operations Reference for OpenClaw
+# Cogmem 3.7.2 Operations Reference for OpenClaw
 
 Read this file when installing, upgrading, importing, repairing, or operating Cogmem. `SKILL.md` contains the decision rules; this file is the command reference.
 
@@ -86,7 +86,7 @@ openclaw gateway restart
 cogmem openclaw diagnose --workspace . --json
 ```
 
-The second command upgrades 3.5.2 schema 24, an existing 3.6.x database, or a pre-release schema-25 test database to the current 3.7.1 schema/projection state in one run. It preserves Raw Ledger evidence. Keep the returned `backupPath` until verification passes. `--dry-run` is read-only and does not create `_schema_migrations`.
+The second command upgrades 3.5.2 schema 24, an existing 3.6.x database, or a pre-release schema-25 test database to the current 3.7.2 schema/projection state in one run. It preserves Raw Ledger evidence. Keep the returned `backupPath` until verification passes. `--dry-run` is read-only and does not create `_schema_migrations`.
 
 After upgrading the package/database, refresh OpenClaw's generated plugin files. `doctor --plugin-only` avoids opening the Cogmem kernel, so it can repair stale `extensions/cogmem-auto-memory/index.js` and `bridge.mjs` even when an old drainer has SQLite busy. Use `connect --auto --force` when intentionally reinstalling the full integration and patching OpenClaw config:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cogmem",
 
-  "version": "3.7.1",
+  "version": "3.7.3",
 
   "type": "module",
   "description": "cogmem — agent-native memory kernel for a single local-first AI agent",