cogmem 3.7.2 → 3.7.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.7.3
+
+- Added enforceable Episode Boundary guardrails with configurable max event, duration, idle-gap, and trusted local-date limits, including best-effort decision audit rows that never roll back successful raw event assignment.
+- Added read-only `cogmem episode audit-boundaries` / MCP `cogmem_episode_audit_boundaries` for bounded episode health diagnostics without Dream, repair, Atlas, binding, activation, or decision-audit writes.
+- Added deterministic read-only `cogmem episode split-plan` / MCP `cogmem_episode_split_plan` previews that preserve logical turns and return `applyableInCurrentVersion=false` with no apply command.
+
 ## 3.7.2
 
 - Fixed Memory Atlas `graph-explore` edge projection so selected action, topic, and ordinary memory edges are merged before the final stable edge limit.

package/MEMORY_MODEL.md

@@ -115,7 +115,7 @@ For pre-answer agent context, prefer `KernelAgentMemoryBackend.recallPack()` whe
 
 Collection routing is enforced in compiled and raw fallback paths. Default recall includes untagged and `collection:anchor` memory. Specialized collections such as `collection:theseus` must be requested explicitly with `collection: "theseus"` or `--collection theseus`.
 
-`MemoryKernel.buildMemoryMap()` and `cogmem memory map` expose a static self-map: anatomy, data lanes, hard bounds, counters, and commands. The map includes episode counts, unassigned raw evidence, and the sealed Episode Dream backlog. Core schema version 24 adds project-scoped topic nodes, aliases, relations and operations; episode cross-references and repair audit; ingest lifecycle state; and per-episode Dream failure details. Production initialization runs migrations; `EpisodeStore.initializeSchema` is compatibility bootstrap for direct tests only, with a parity test against migrations 22–24. Use `cogmem migrate --dry-run --json` before an upgrade and `cogmem migrate --yes --backup` to apply it without rewriting Raw Ledger evidence.
+`MemoryKernel.buildMemoryMap()` and `cogmem memory map` expose a static self-map: anatomy, data lanes, hard bounds, counters, and commands. The map includes episode counts, unassigned raw evidence, and the sealed Episode Dream backlog. Core schema version 28 includes project-scoped topic nodes, aliases, relations and operations; episode cross-references and repair audit; ingest lifecycle state; per-episode Dream failure details; and best-effort episode boundary decision audit rows. Production initialization runs migrations; `EpisodeStore.initializeSchema` is compatibility bootstrap for direct tests only, with a parity test against episode migrations 22–28. Use `cogmem migrate --dry-run --json` before an upgrade and `cogmem migrate --yes --backup` to apply it without rewriting Raw Ledger evidence.
 
 Graph edge confidence, stability, and activation are separate. Recall and maintenance may decay activation, but they must not decay provenance confidence or the stability of `SUPPORTS`, `CORRECTS`, `CONTRADICTS`, and `SUPERSEDES` evidence. `BrainGraphView` is a bounded read-only traversal surface; it cannot mutate canonical memory.
 

package/README.md

@@ -11,7 +11,7 @@ It is not a knowledge-base app, a note-taking app, a vector RAG wrapper, an Obsi
 
 ## Status
 
-Current version: `3.7.2`
+Current version: `3.7.3`
 
 Distribution: npm registry. GitHub remains the source mirror and hosts this installer, but package install and upgrade resolve `cogmem` from npm by default.
 
@@ -229,7 +229,7 @@ cogmem migrate --dry-run --json
 
 For a manual migration, run `cogmem migrate --yes --backup`. The migration runner adopts the existing `_meta.schema_version`, applies only later idempotent migrations, preserves Raw Ledger rows, and creates a timestamped, transaction-consistent standalone database backup before changing an on-disk database. The backup includes committed SQLite WAL pages instead of copying only the main database file.
 
-Upgrade a 3.5.2 database, a 3.6.x database, or a pre-release schema-25 test database into the current 3.7.2 schema and projection set with one command:
+Upgrade a 3.5.2 database, a 3.6.x database, or a pre-release schema-25 test database into the current 3.7.3 schema and projection set with one command:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -278,11 +278,12 @@ cogmem dream tick --project my-agent --mode auto --max-episodes 10 --json
 
 Raw events are always written first. `KernelAgentMemoryBackend` and OpenClaw plugin 0.7.1 assemble live turns automatically. The foreground hook uses deterministic rules and previous assistant/user context; background import and repair paths may use the advisory hybrid classifier. Advisory output is allow-listed and cannot directly mutate durable memory. Unknown turns now fail closed as ambiguous. Continuation requires explicit continuation language or project/topic/entity/semantic overlap; Cogmem does not route domains with an expanding hard-coded keyword dictionary.
 
-Hookless MCP agents can call `cogmem_episode_append` or bounded `cogmem_episode_import`. Existing OpenClaw/Hermes import commands use stable content identities and the same episode schema. Low-confidence imported groups soft-seal for review unless an operator explicitly forces sealing. Cogmem skips import batch sealing for empty episode boundaries and skips legacy empty Dream jobs so one bad imported episode cannot block the queue. Episode semantic summaries and closure receipts are control hints, never durable evidence; every Dream candidate must cite a non-empty subset of the episode's raw event IDs and still pass CPU governance.
+Hookless MCP agents can call `cogmem_episode_append` or bounded `cogmem_episode_import`. Existing OpenClaw/Hermes import commands use stable content identities and the same episode schema. Low-confidence imported groups soft-seal for review unless an operator explicitly forces sealing. Episode boundary guardrails can enforce configurable max-event, duration, idle-gap, and trusted local-date limits before advisory review, while decision audit writes remain best-effort. Cogmem skips import batch sealing for empty episode boundaries and skips legacy empty Dream jobs so one bad imported episode cannot block the queue. Episode semantic summaries and closure receipts are control hints, never durable evidence; every Dream candidate must cite a non-empty subset of the episode's raw event IDs and still pass CPU governance.
 
 User-shaped topic state is project-scoped. Explicit user operations become active and auditable; model-proposed topics, aliases, and relations remain candidates. Use MCP `cogmem_topic_list` to inspect nodes, `cogmem_topic_operate` to create, rename, alias, move, merge, split, or relate topics, and `cogmem_topic_rollback` to reverse an audited operation. Alias collisions fail closed as `needs_review`; applications can also call `TopicGovernance.rollback()` through the public API.
 
 Episode surgery is available through `cogmem episode split|merge|move-event|reclassify|requeue-dream` or MCP `cogmem_episode_repair`. Structural repair recomputes closure receipts, invalidates candidates derived from the old episode boundary, preserves cross-references, requeues eligible sealed episodes, and writes an audit record.
+Use `cogmem episode audit-boundaries` for read-only boundary diagnostics and `cogmem episode split-plan` for deterministic read-only split previews. The split preview does not call repair, does not move events, and returns no executable apply command in 3.7.3.
 
 Inspect queue state:
 
@@ -798,7 +799,7 @@ npm pack --dry-run --json
 npm publish --dry-run --access public
 ```
 
-Create a GitHub Release from the matching version tag, for example `v3.7.2`. The `.github/workflows/publish.yml` workflow publishes to npm only when the release is published, not when a tag is pushed. The npm Trusted Publisher entry must match repository `liuqin164/cogmem`, workflow file `publish.yml`, and environment `npm publish`.
+Create a GitHub Release from the matching version tag, for example `v3.7.3`. The `.github/workflows/publish.yml` workflow publishes to npm only when the release is published, not when a tag is pushed. The npm Trusted Publisher entry must match repository `liuqin164/cogmem`, workflow file `publish.yml`, and environment `npm publish`.
 
 Publish manually only for emergency fallback:
 

package/RELEASE_CHECKLIST.md

@@ -1,11 +1,11 @@
-# cogmem 3.7.2 Release Checklist
+# cogmem 3.7.3 Release Checklist
 
 This release is distributed through the npm registry. GitHub remains the source and review mirror.
 
 ## Required Metadata
 
 - `package.json` name is `cogmem`.
-- `package.json` version is `3.7.2`.
+- `package.json` version is `3.7.3`.
 - `package.json` has `publishConfig.access = public`.
 - Public export `.` points to `dist/public.js` and `dist/public.d.ts`.
 - Internal subpath `./internal` exists only as an explicit advanced subpath.
@@ -39,7 +39,7 @@ This release is distributed through the npm registry. GitHub remains the source
 - `cogmem episode`
 - `cogmem dream`
 
-MCP `tools/list` includes strategy, episode append/import/status/seal/repair, topic list/operate/rollback, candidate review, conditional Dream tick/status, prospective tools, all seven read-only Memory Atlas queries, and explicit `cogmem_graph_touch`. Atlas queries declare read-only/idempotent semantics and never change activation; only touch records selected-node use. Episode append/import never run Dream. MCP Dream tick requires `maintenanceMode: true` to process work; otherwise it is recommendation-only.
+MCP `tools/list` includes strategy, episode append/import/status/audit-boundaries/split-plan/seal/repair, topic list/operate/rollback, candidate review, conditional Dream tick/status, prospective tools, all seven read-only Memory Atlas queries, and explicit `cogmem_graph_touch`. Atlas queries declare read-only/idempotent semantics and never change activation; only touch records selected-node use. Episode append/import never run Dream. Episode audit-boundaries and split-plan are read-only and never repair, split, Dream, Atlas, bind, or update activation. MCP Dream tick requires `maintenanceMode: true` to process work; otherwise it is recommendation-only.
 
 ## Required Documentation
 
@@ -61,7 +61,7 @@ MCP `tools/list` includes strategy, episode append/import/status/seal/repair, to
 - README and skills explain Raw Ledger-first episode assembly, soft/hard sealing, explicit conditional Dream ticks, raw-event evidence grounding, repair/retry, and hookless Hermes MCP/import usage.
 - README and skills give the full post-import maintenance sequence: status, episode status, Dream status, bounded Dream tick, candidate listing, govern candidate, needs-confirmation listing, explicit review, and recall verification.
 - README and skills explain that 3.6.4+ skips empty imported episode boundaries and legacy empty Dream jobs instead of letting them abort `dream tick`.
-- README and skills explain the 3.7.2 agent operations protocol: `memory plan` for next actions, default grouped `memory candidates --json`, `memory list --since/--until/--order`, historical-discussion recall intent, Atlas canonical cards, `matchedFacets`, `relatedButNotSelected`, `relaxationTrace`, Atlas evidence `sourceLocator`, and cursor-based `memory bind`.
+- README and skills explain the 3.7.3 agent operations protocol: `memory plan` for next actions, default grouped `memory candidates --json`, `memory list --since/--until/--order`, historical-discussion recall intent, Atlas canonical cards, `matchedFacets`, `relatedButNotSelected`, `relaxationTrace`, Atlas evidence `sourceLocator`, cursor-based `memory bind`, and read-only episode boundary audit/split planning.
 - README, `MEMORY_ATLAS.md`, and installed skills explain the multi-dimensional Atlas model: a canonical episode/raw event exists once, facet nodes connect through typed edges, query results intersect facets, and display/injection dedupes by `canonicalId`.
 - `connect openclaw|hermes --json` documents structured `nextSteps`; `nextCommands` must contain only agent-safe, non-interactive commands and must not include `cogmem init`, `cogmem-init`, gateway restart, or Hermes reload.
 - README and skills document `cogmem mcp` as the preferred MCP server command for new configs while preserving `cogmem-mcp` as a compatibility bin.
@@ -94,7 +94,7 @@ npm publish --dry-run --access public
 
 The pack dry-run must include built public API files, CLI files, examples, docs, and `install.sh`. It must not include local databases or machine-specific files.
 
-After verification, create a GitHub Release from the matching version tag, for example `v3.7.2`. The release workflow publishes through npm Trusted Publishing when the release is published. It must not publish on tag push alone.
+After verification, create a GitHub Release from the matching version tag, for example `v3.7.3`. The release workflow publishes through npm Trusted Publishing when the release is published. It must not publish on tag push alone.
 
 Emergency manual fallback:
 

package/dist/belief/BeliefStore.d.ts

@@ -1,3 +1,4 @@
+import Database from 'bun:sqlite';
 import type { BeliefCandidate, BeliefConflictCandidate, BeliefEvidenceRecord, BeliefRecord, BeliefRevisionDecision } from '../types/index.js';
 import { EventStore } from '../store/EventStore.js';
 import type { PolicyExecutionRecord } from '../store/PolicyExecutionStore.js';
@@ -6,8 +7,9 @@ export declare class BeliefStore {
     private static readonly SOURCE_TRUST;
     private static readonly SCOPE_PRIORITY;
     private db;
+    private ownsDb;
     private closed;
-    constructor(dbPath?: string, eventStore?: EventStore | undefined);
+    constructor(dbPath?: string | Database, eventStore?: EventStore | undefined);
     private initializeSchema;
     findByCanonicalKey(canonicalKey: string): BeliefRecord[];
     countActive(projectId?: string): number;

package/dist/belief/BeliefStore.js

@@ -20,10 +20,17 @@ export class BeliefStore {
         global: 1
     };
     db;
+    ownsDb = true;
     closed = false;
     constructor(dbPath = ':memory:', eventStore) {
         this.eventStore = eventStore;
-        this.db = new Database(dbPath);
+        if (dbPath instanceof Database) {
+            this.db = dbPath;
+            this.ownsDb = false;
+        }
+        else {
+            this.db = new Database(dbPath);
+        }
         this.initializeSchema();
     }
     initializeSchema() {
@@ -892,7 +899,8 @@ export class BeliefStore {
     close() {
         if (this.closed)
             return;
-        this.db.close();
+        if (this.ownsDb)
+            this.db.close();
         this.closed = true;
     }
 }

package/dist/bin/episode.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { createReadStream, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { createInterface } from 'node:readline';
 import { createStableImportIdentityFactory } from '../episode/EpisodeImportIdentity.js';
 import { createMemoryKernel, createMemoryKernelFromConfig } from '../factory.js';
@@ -24,12 +25,15 @@ function parseArgs(argv) {
 }
 function usage() {
     return [
-        'Usage: cogmem episode <append|import|list|get|seal|status|repair|split|merge|move-event|reclassify|requeue-dream> [args]',
+        'Usage: cogmem episode <append|import|list|get|seal|status|audit-boundaries|boundary-decisions|split-plan|repair|split|merge|move-event|reclassify|requeue-dream> [args]',
         '  append --project <id> --session <id> --source-agent <id> --role <role> --text <text>',
         '  import --project <id> --session <id> --source-agent <id> --format jsonl --file <path> [--seal-batch] [--force-seal] [--chunk-size <n>] [--checkpoint-file <path>] [--resume] [--start-line <n>] [--end-line <n>] [--max-lines <n>] [--skip-errors] [--max-errors <n>]',
         '  list|status [--project <id>] [--session <id>] [--json]',
-        '  get --episode <id> [--json]',
-        '  seal --episode <id> [--mode soft|hard|manual|batch] [--reason <reason>]',
+        '  get --project <id> --episode <id> [--json]',
+        '  seal --project <id> --episode <id> [--mode soft|hard|manual|batch] [--reason <reason>]',
+        '  audit-boundaries --project <id> [--episode <id>] [--status open|soft_sealed|sealed] [--limit <n>] [--cursor <cursor>]',
+        '  boundary-decisions --project <id> [--event <eventId>] [--limit <n>]',
+        '  split-plan --project <id> --episode <id> [--include-event-ids]',
         '  repair [--project <id>] [--since <globalSeq>] [--limit <n>]',
         '  split --project <id> --episode <id> --events <eventId,eventId>',
         '  merge --project <id> --source-episode <id> --target-episode <id>',
@@ -62,6 +66,8 @@ async function main() {
                 projectId: requiredArg(args, 'project'), sessionId: requiredArg(args, 'session'),
                 sourceAgent: requiredArg(args, 'source-agent'), role: roleArg(args.role), text: requiredArg(args, 'text'),
                 externalMessageId: stringArg(args, 'external-id'), timestamp: numberArg(args, 'timestamp'),
+                threadId: stringArg(args, 'thread-id'), turnId: stringArg(args, 'turn-id'), turnSeq: numberArg(args, 'turn-seq'),
+                localDate: stringArg(args, 'local-date'), eventOrdinal: numberArg(args, 'event-ordinal'),
             });
         }
         else if (args.command === 'import') {
@@ -74,14 +80,44 @@ async function main() {
             result = { episodes: kernel.listEpisodes({ projectId, sessionId, limit: numberArg(args, 'limit') }), dream: kernel.getEpisodeDreamStatus(projectId) };
         }
         else if (args.command === 'get') {
+            const requestedProject = requiredArg(args, 'project');
             const episodeId = requiredArg(args, 'episode');
-            result = { episode: kernel.getEpisode(episodeId), events: kernel.listEpisodeEventLinks(episodeId), closureReceipts: kernel.listEpisodeClosureReceipts({ episodeId }) };
+            const episode = kernel.getEpisode(episodeId);
+            if (!episode || episode.projectId !== requestedProject)
+                throw new Error(`episode_project_mismatch:${episodeId}`);
+            result = { episode, events: kernel.listEpisodeEventLinks(episodeId), closureReceipts: kernel.listEpisodeClosureReceipts({ episodeId, projectId: requestedProject }) };
         }
         else if (args.command === 'seal') {
-            result = kernel.sealEpisode(requiredArg(args, 'episode'), {
+            const episodeId = requiredArg(args, 'episode');
+            const requestedProject = requiredArg(args, 'project');
+            const episode = kernel.getEpisode(episodeId);
+            if (!episode || episode.projectId !== requestedProject)
+                throw new Error(`episode_project_mismatch:${episodeId}`);
+            result = kernel.sealEpisode(episodeId, {
                 mode: closureModeArg(stringArg(args, 'mode')), reason: stringArg(args, 'reason') || 'cli_manual_seal',
             });
         }
+        else if (args.command === 'audit-boundaries') {
+            result = kernel.auditEpisodeBoundaries({
+                projectId: requiredArg(args, 'project'), episodeId: stringArg(args, 'episode'),
+                status: statusArg(stringArg(args, 'status')), limit: numberArg(args, 'limit'), cursor: stringArg(args, 'cursor'),
+                maxEvents: numberArg(args, 'max-events'), maxDurationMs: numberArg(args, 'max-duration-ms'),
+                maxIdleGapMs: numberArg(args, 'max-idle-gap-ms'), timezone: stringArg(args, 'timezone'),
+            });
+        }
+        else if (args.command === 'boundary-decisions') {
+            result = { decisions: kernel.listEpisodeBoundaryDecisions({
+                    projectId: requiredArg(args, 'project'), primaryEventId: stringArg(args, 'event'), limit: numberArg(args, 'limit'),
+                }) };
+        }
+        else if (args.command === 'split-plan') {
+            result = kernel.planEpisodeSplit({
+                projectId: requiredArg(args, 'project'), episodeId: requiredArg(args, 'episode'),
+                maxEvents: numberArg(args, 'max-events'), maxDurationMs: numberArg(args, 'max-duration-ms'),
+                maxIdleGapMs: numberArg(args, 'max-idle-gap-ms'), timezone: stringArg(args, 'timezone'),
+                includeEventIds: args['include-event-ids'] === true,
+            });
+        }
         else if (args.command === 'repair') {
             result = kernel.repairEpisodes({ projectId, sinceGlobalSeq: numberArg(args, 'since'), limit: numberArg(args, 'limit') });
         }
@@ -126,9 +162,17 @@ async function importJsonl(kernel, args) {
     const file = requiredArg(args, 'file');
     const checkpointFile = stringArg(args, 'checkpoint-file') || `${file}.cogmem-checkpoint.json`;
     const chunkSize = Math.max(1, Math.min(Math.trunc(numberArg(args, 'chunk-size') ?? 500), 5000));
+    const fileHash = createHash('sha256').update(readFileSync(file)).digest('hex');
     const checkpoint = args.resume === true && existsSync(checkpointFile)
         ? JSON.parse(readFileSync(checkpointFile, 'utf8'))
         : {};
+    const checkpointPrefixHash = checkpoint.processedLine ? sourcePrefixHash(file, checkpoint.processedLine) : undefined;
+    if (args.resume === true && checkpoint.fileHash && ((checkpoint.processedPrefixHash ? checkpoint.processedPrefixHash !== checkpointPrefixHash : checkpoint.fileHash !== fileHash)
+        || checkpoint.projectId !== projectId
+        || checkpoint.sourceAgent !== sourceAgent
+        || checkpoint.sessionId !== sessionId
+        || checkpoint.format !== format))
+        throw new Error('episode_import_checkpoint_source_mismatch');
     const resumeAfter = Math.max(0, checkpoint.processedLine || 0);
     const startLine = Math.max(1, Math.trunc(numberArg(args, 'start-line') ?? 1));
     const endLine = Math.max(startLine, Math.trunc(numberArg(args, 'end-line') ?? Number.MAX_SAFE_INTEGER));
@@ -151,15 +195,38 @@ async function importJsonl(kernel, args) {
     let duplicates = 0;
     let processed = 0;
     let lineNumber = 0;
+    let lastProcessedLine = resumeAfter;
     let selectedLines = 0;
+    let windowStopped = false;
     const errors = [];
     const reader = createInterface({ input: createReadStream(file, { encoding: 'utf8' }), crlfDelay: Infinity });
     for await (const rawLine of reader) {
         lineNumber += 1;
         if (!rawLine.trim())
             continue;
-        if (lineNumber > endLine || selectedLines >= maxLines)
+        if (lineNumber > endLine || selectedLines >= maxLines) {
+            windowStopped = true;
             break;
+        }
+        if (lineNumber <= resumeAfter || lineNumber < startLine) {
+            // Rebuild only the deterministic fallback identity state. A malformed
+            // skipped line must remain skipped during resume.
+            try {
+                const prior = JSON.parse(rawLine);
+                const priorText = typeof prior.text === 'string' ? prior.text : typeof prior.content === 'string' ? prior.content : undefined;
+                const hasExplicitIdentity = typeof prior.externalMessageId === 'string' || typeof prior.id === 'string';
+                if (priorText && !hasExplicitIdentity) {
+                    const priorSession = typeof prior.sessionId === 'string' ? prior.sessionId : sessionId;
+                    const priorRole = roleValue(prior.role);
+                    const priorTimestamp = prior.timestamp === undefined ? undefined : timeValue(prior.timestamp);
+                    getIdentity(priorSession)({ role: priorRole, text: priorText, timestamp: priorTimestamp });
+                }
+            }
+            catch {
+                // The checkpoint already records this line as skipped/failed.
+            }
+            continue;
+        }
         try {
             const message = JSON.parse(rawLine);
             const text = typeof message.text === 'string' ? message.text : typeof message.content === 'string' ? message.content : undefined;
@@ -170,21 +237,24 @@ async function importJsonl(kernel, args) {
             const resolvedSessionId = typeof message.sessionId === 'string' ? message.sessionId : sessionId;
             const role = roleValue(message.role);
             const timestamp = timeValue(message.timestamp);
+            const threadId = typeof message.threadId === 'string' ? message.threadId : undefined;
+            const turnId = typeof message.turnId === 'string' ? message.turnId : undefined;
+            const turnSeq = typeof message.turnSeq === 'number' && Number.isFinite(message.turnSeq) ? message.turnSeq : undefined;
+            const localDate = typeof message.localDate === 'string' ? message.localDate : undefined;
+            const eventOrdinal = typeof message.eventOrdinal === 'number' && Number.isFinite(message.eventOrdinal) ? message.eventOrdinal : undefined;
             const externalMessageId = typeof message.externalMessageId === 'string'
                 ? message.externalMessageId
                 : typeof message.id === 'string'
                     ? message.id
                     : getIdentity(resolvedSessionId)({ role, text, timestamp });
-            // Rebuild occurrence counters while streaming past the checkpoint/start line.
-            if (lineNumber <= resumeAfter || lineNumber < startLine)
-                continue;
             selectedLines += 1;
             const result = await kernel.appendEpisodeMessageAsync({
-                projectId, sourceAgent, sessionId: resolvedSessionId, role, text, timestamp,
+                projectId, sourceAgent, sessionId: resolvedSessionId, role, text, timestamp, threadId, turnId, turnSeq, localDate, eventOrdinal,
                 externalMessageId,
                 metadata: { imported: true, importFormat: format },
             });
             processed += 1;
+            lastProcessedLine = lineNumber;
             result.created ? imported += 1 : duplicates += 1;
             if (result.episodeId)
                 episodeIds.add(result.episodeId);
@@ -193,27 +263,35 @@ async function importJsonl(kernel, args) {
             if (result.ignored)
                 ignoredEventIds.push(result.eventId);
             if (processed % chunkSize === 0)
-                writeCheckpoint(checkpointFile, { processedLine: lineNumber, lastProcessedLine: lineNumber, processed, projectId, sourceAgent, sessionId });
+                writeCheckpoint(checkpointFile, {
+                    processedLine: lineNumber, lastProcessedLine: lineNumber, processed, projectId, sourceAgent, sessionId, format, fileHash,
+                    processedPrefixHash: sourcePrefixHash(file, lineNumber), fileCompleted: false, windowCompleted: false,
+                });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             errors.push({ line: lineNumber, error: message });
             writeCheckpoint(checkpointFile, {
                 failedAtLine: lineNumber, error: message, resumeFrom: lineNumber,
-                lastProcessedLine: Math.max(resumeAfter, lineNumber - 1), processedLine: Math.max(resumeAfter, lineNumber - 1),
-                processed, projectId, sourceAgent, sessionId,
+                lastProcessedLine, processedLine: lastProcessedLine,
+                processed, projectId, sourceAgent, sessionId, format, fileHash, processedPrefixHash: sourcePrefixHash(file, lastProcessedLine), fileCompleted: false, windowCompleted: false,
             });
             if (!skipErrors || errors.length > maxErrors)
                 throw error;
+            lastProcessedLine = lineNumber;
         }
     }
-    writeCheckpoint(checkpointFile, { processedLine: lineNumber, processed, projectId, sourceAgent, sessionId, completed: true });
+    writeCheckpoint(checkpointFile, {
+        processedLine: lastProcessedLine, processed, projectId, sourceAgent, sessionId, format, fileHash, processedPrefixHash: sourcePrefixHash(file, lastProcessedLine),
+        completed: !windowStopped, fileCompleted: !windowStopped, windowCompleted: true,
+        hasMore: windowStopped, nextLine: windowStopped ? lineNumber : undefined,
+    });
     const closureReceipts = args['seal-batch'] === true
         ? [...episodeIds].map((episodeId) => kernel.sealImportedEpisode(episodeId, { reason: 'cli_batch_boundary', force: args['force-seal'] === true }))
         : [];
     return {
         importId: `episode-import:${sourceAgent}:${sessionId}`,
-        imported, duplicates, processed, errors, resumeFrom: lineNumber + 1, checkpointFile,
+        imported, duplicates, processed, errors, resumeFrom: lastProcessedLine + 1, checkpointFile,
         episodeIds: [...episodeIds], unassignedEventIds, ignoredEventIds, closureReceipts, dreamRan: false,
     };
 }
@@ -222,6 +300,10 @@ function writeCheckpoint(path, value) {
     writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
     renameSync(temporary, path);
 }
+function sourcePrefixHash(file, lines) {
+    const text = readFileSync(file, 'utf8');
+    return createHash('sha256').update(text.split(/\r?\n/u).slice(0, Math.max(0, lines)).join('\n')).digest('hex');
+}
 function stringArg(args, key) { return typeof args[key] === 'string' && args[key] ? args[key] : undefined; }
 function requiredArg(args, key) { const value = stringArg(args, key); if (!value)
     throw new Error(`--${key} is required`); return value; }
@@ -248,6 +330,13 @@ function dreamModeArg(value) {
         return value;
     throw new Error('mode must be micro, normal, or deep');
 }
+function statusArg(value) {
+    if (!value)
+        return undefined;
+    if (value === 'open' || value === 'soft_sealed' || value === 'sealed')
+        return value;
+    throw new Error('status must be open, soft_sealed, or sealed');
+}
 function episodeTypeArg(value) {
     if (!value)
         return undefined;
@@ -256,6 +345,8 @@ function episodeTypeArg(value) {
     throw new Error('invalid episode type');
 }
 function timeValue(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
     if (typeof value === 'number' && Number.isFinite(value))
         return value;
     if (typeof value === 'string') {
@@ -263,6 +354,6 @@ function timeValue(value) {
         if (!Number.isNaN(parsed))
             return parsed;
     }
-    return undefined;
+    throw new Error('timestamp must be a finite number or parseable date');
 }
 main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });

package/dist/bin/import-support.js

@@ -336,22 +336,26 @@ async function recordRawImportedEvidence(kernel, projectId, envelope) {
     const threadId = sourceRef?.threadId || stringRecordField(metadata.threadId) || record.provenance.sourceId;
     const sessionId = sourceRef?.sessionId || stringRecordField(metadata.sessionId) || record.provenance.sourceId;
     const eventOrdinal = sourceRef?.eventOrdinal ?? sourceRef?.sourceOffset;
-    const importAnchor = [
-        record.provenance.sourceId,
-        record.recordId,
-        sourceRef?.sourcePath,
-        sourceRef?.lineStart,
-        sourceRef?.lineEnd,
-        eventOrdinal,
-    ].filter((item) => item !== undefined && item !== null && String(item).length > 0).join(':');
+    const allowNonUserEpisodeStart = metadata.importedSummarySupport === true || record.provenance.reliabilityClass === 'imported_summary';
+    const importAnchor = createHash('sha256').update(JSON.stringify({
+        sourceId: record.provenance.sourceId,
+        recordId: record.recordId ?? null,
+        sourcePath: sourceRef?.sourcePath ?? null,
+        lineStart: sourceRef?.lineStart ?? null,
+        lineEnd: sourceRef?.lineEnd ?? null,
+        eventOrdinal: eventOrdinal ?? null,
+    })).digest('hex');
+    const contentHash = createHash('sha256').update(record.text).digest('hex');
     const existing = findImportedRawAnchor(kernel, {
         projectId,
         threadId,
         sourceId: record.provenance.sourceId,
         importAnchor,
-        contentHash: createHash('sha256').update(record.text).digest('hex'),
+        contentHash,
     });
     if (existing) {
+        if (existing.contentHash !== contentHash)
+            throw new Error(`import_anchor_content_conflict:${importAnchor}`);
         let link = kernel.episodeStore.getEventLink(existing.eventId);
         if (!link && !kernel.episodeStore.hasEventDisposition(existing.eventId)) {
             await kernel.assembleEpisodeTurnAsync([existing], {
@@ -359,6 +363,7 @@ async function recordRawImportedEvidence(kernel, projectId, envelope) {
                 sessionId,
                 sourceAgent: record.provenance.sourceType || record.provenance.sourceId,
                 now: record.timestamp,
+                allowNonUserEpisodeStart,
             });
             link = kernel.episodeStore.getEventLink(existing.eventId);
         }
@@ -371,6 +376,8 @@ async function recordRawImportedEvidence(kernel, projectId, envelope) {
         sessionId,
         turnId: sourceRef?.turnId || record.turnId || record.recordId,
         turnSeq: sourceRef?.turnSeq,
+        localDate: localDateFromTimestamp(record.timestamp),
+        localDateSource: 'generated_utc',
         role,
         rawEventType: 'message',
         content: record.text,
@@ -400,19 +407,29 @@ async function recordRawImportedEvidence(kernel, projectId, envelope) {
         sessionId,
         sourceAgent: record.provenance.sourceType || record.provenance.sourceId,
         now: record.timestamp,
+        allowNonUserEpisodeStart,
     });
     return { event, created: true, episodeId: assembly.episode?.episodeId };
 }
 function findImportedRawAnchor(kernel, input) {
-    return kernel.getThreadEvents(input.threadId, { projectId: input.projectId }).find((event) => {
+    const indexed = kernel.eventStore.findImportedEventAnchor(input.projectId, input.sourceId, input.importAnchor);
+    if (indexed)
+        return indexed;
+    return kernel.getThreadEvents(input.threadId, { projectId: input.projectId, limit: 10_000 }).find((event) => {
         const payload = event.payload;
         return event.sourceId === input.sourceId
-            && (payload.metadata?.importAnchor === input.importAnchor || event.contentHash === input.contentHash);
+            && payload.metadata?.importAnchor === input.importAnchor;
     });
 }
 function stringRecordField(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
+function localDateFromTimestamp(timestamp) {
+    if (typeof timestamp !== 'number' || !Number.isFinite(timestamp))
+        return undefined;
+    const date = new Date(timestamp);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10);
+}
 function openKernel(args, workspaceRoot) {
     const explicitDb = stringArg(args, 'db');
     if (explicitDb) {

package/dist/config/CogmemConfig.d.ts

@@ -1,6 +1,7 @@
 import type { MemoryKernelOptions } from '../factory.js';
 import { ModelRegistry } from '../models/ModelRegistry.js';
 import { type ConfigDiagnosticLike } from './VectorDimension.js';
+export type { ConfigDiagnosticLike } from './VectorDimension.js';
 export type CogmemConfigKind = 'toml' | 'missing';
 export type EnvLike = Record<string, string | undefined>;
 export interface CogmemConfigResolution {

package/dist/config/CogmemConfig.js

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { AesGcmEncryptionProvider } from '../encryption/index.js';
 import { ModelRegistry } from '../models/ModelRegistry.js';
 import { DEFAULT_VECTOR_DIMENSION, addVectorDimensionDiagnostics, parseVectorDimensionValue, } from './VectorDimension.js';
+import { normalizeEpisodeBoundaryConfig } from '../episode/EpisodeBoundaryPolicy.js';
 export function defaultCogmemHome(env = process.env) {
     return join(env.HOME || homedir(), '.cogmem');
 }
@@ -53,6 +54,7 @@ export function loadCogmemConfig(options = {}) {
     const memoryModel = section(root, 'memory_model');
     const reasoningModel = section(root, 'reasoning_model');
     const governance = section(root, 'governance');
+    const episodeBoundary = section(root, 'episode_boundary');
     const integrations = section(root, 'integrations');
     const openclaw = section(integrations, 'openclaw');
     const hermes = section(integrations, 'hermes');
@@ -101,6 +103,25 @@ export function loadCogmemConfig(options = {}) {
     }
     if (Object.keys(redactionPolicy).length > 0)
         optionsOut.redactionPolicy = redactionPolicy;
+    const boundaryInput = {
+        enabled: boundaryBoolean(episodeBoundary.enabled, 'enabled', diagnostics),
+        mode: boundaryString(episodeBoundary.mode, 'mode', diagnostics),
+        maxEvents: boundaryNumber(episodeBoundary.max_events, 'max_events', diagnostics),
+        maxDurationMs: boundaryNumber(episodeBoundary.max_duration_ms, 'max_duration_ms', diagnostics),
+        maxIdleGapMs: boundaryNumber(episodeBoundary.max_idle_gap_ms, 'max_idle_gap_ms', diagnostics),
+        splitOnTrustedLocalDateChange: boundaryBoolean(episodeBoundary.split_on_trusted_local_date_change, 'split_on_trusted_local_date_change', diagnostics),
+        auditDecisions: boundaryBoolean(episodeBoundary.audit_decisions, 'audit_decisions', diagnostics),
+        applyToLive: boundaryBoolean(episodeBoundary.apply_to_live, 'apply_to_live', diagnostics),
+        applyToImports: boundaryBoolean(episodeBoundary.apply_to_imports, 'apply_to_imports', diagnostics),
+        policyVersion: boundaryString(episodeBoundary.policy_version, 'policy_version', diagnostics),
+        timezone: boundaryString(episodeBoundary.timezone, 'timezone', diagnostics),
+    };
+    const configuredBoundary = Object.values(boundaryInput).some((value) => value !== undefined);
+    if (configuredBoundary) {
+        const normalizedBoundary = normalizeEpisodeBoundaryConfig(boundaryInput);
+        optionsOut.episodeBoundary = normalizedBoundary.config;
+        diagnostics.push(...normalizedBoundary.diagnostics);
+    }
     const encryptionEnabled = booleanValue(governance.encryption) === true;
     const encryptionPassphrase = interpolate(stringValue(governance.encryption_passphrase) || stringValue(governance.passphrase) || '', env, diagnostics);
     if (encryptionEnabled) {
@@ -245,3 +266,27 @@ function booleanValue(value) {
 function numberValue(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
+function boundaryBoolean(value, name, diagnostics) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'boolean')
+        return value;
+    diagnostics.push({ severity: 'warning', code: `invalid_episode_boundary_${name}_type`, message: `episode_boundary.${name} must be a boolean.` });
+    return undefined;
+}
+function boundaryNumber(value, name, diagnostics) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    diagnostics.push({ severity: 'warning', code: `invalid_episode_boundary_${name}_type`, message: `episode_boundary.${name} must be a finite number.` });
+    return undefined;
+}
+function boundaryString(value, name, diagnostics) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    diagnostics.push({ severity: 'warning', code: `invalid_episode_boundary_${name}_type`, message: `episode_boundary.${name} must be a string.` });
+    return undefined;
+}

package/dist/core/MemoryGraph.js

@@ -14,15 +14,27 @@ export class MemoryGraph {
     anchorIndex = new Map();
     topicReclassifiedListeners = new Set();
     constructor(dbPath = ':memory:') {
-        try {
-            this.db = new Database(dbPath);
-            this.initializeSchema();
-            this.rebuildIndexes();
-        }
-        catch (error) {
-            logger.error('Failed to initialize MemoryGraph:', error);
-            throw new Error(`MemoryGraph initialization failed: ${error}`);
+        let lastError;
+        for (let attempt = 0; attempt < 6; attempt += 1) {
+            try {
+                this.db = new Database(dbPath);
+                this.initializeSchema();
+                this.rebuildIndexes();
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                try {
+                    this.db?.close();
+                }
+                catch { }
+                if (!isSqliteBusy(error) || attempt === 5)
+                    break;
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
+            }
         }
+        logger.error('Failed to initialize MemoryGraph:', lastError);
+        throw new Error(`MemoryGraph initialization failed: ${lastError}`);
     }
     initializeSchema() {
         this.db.exec(`
@@ -858,3 +870,8 @@ export class MemoryGraph {
         }
     }
 }
+function isSqliteBusy(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error?.code;
+    return code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED' || /database is locked|SQLITE_BUSY|SQLITE_LOCKED/i.test(message);
+}