cogmem 3.6.2

package/RECALL_EXPLAINABILITY.md

@@ -0,0 +1,152 @@
+# Recall Explainability
+
+Agent-facing recall is governed by default. `KernelAgentMemoryBackend.recall()` and `MemoryKernel.navigateMemory()` return active evidence only after scope, status, trust, and budget filtering.
+
+## Included Evidence
+
+`explainRecallWithKernel()` reports why evidence entered the recall result:
+
+- `activationPath`: the recall path, such as pulse, temporal traversal, or fallback.
+- `whyMatched`: agent scope, provenance, pulse fusion, temporal branch, and governance reasons.
+- `sourceAnchor`: the drill-down anchor for the semantic memory source event.
+
+`sourceAnchor` contains:
+
+- `eventId`: the memory event that recorded the semantic ingest.
+- `sourceEventType`: usually `INGESTED`.
+- `sourceRefs`: raw event, source path, thread, line, turn, and ordinal anchors when available.
+- `context`: surrounding ledger context for the source event.
+
+For agent lifecycle events, source refs may point to `message`, `tool_call`, `tool_result`, or `task_event` raw ledger entries. For normalized JSON/CSV imports, source refs preserve original source offset and row/line anchors when available, even though ingestion flows through Markdown projection.
+
+`KernelAgentMemoryBackend.recall()` also returns `sourceContext` on agent-facing items when a raw event can be resolved. `sourceContext` contains the raw event text, stable display labels, bounded before/after events, parent/child links, strict window metadata, optional source/character ranges, and a `sourceLocator` command:
+
+```bash
+cogmem memory show --event <eventId> --before 2 --after 2
+```
+
+Agents should use `sourceContext` when the user asks what was specifically said, how a conclusion was explained, or what happened before/after a remembered point. If `canAnswerExactQuote=false`, the item is only a clue until the raw source event is inspected.
+
+Every `sourceContext` event has a `label` suitable for prompt injection and cross-reference, usually derived from host message id metadata or the ledger `globalSeq`. When available, `charRange` gives the original source character range and `sourceRange` carries source offset, line range, and source character range. `sourceContext.window` states the requested before/after counts, actual counts, ordering (`chronological`), role filter (`all`), `excludesAnchor=true`, and overlap handling (`drop_from_after`). Agents should prefer these fields over guessing whether before/after includes the anchor.
+
+When automatic prompt injection is missing or insufficient, agents can actively query the same governed path:
+
+```bash
+cogmem memory recall --query "<user question>" --project <project> --agent <agent> --json
+```
+
+This command returns `queryPlan`, `items`, `sourceAnchor`, and `sourceContext`. It is the preferred fallback before searching legacy host files.
+
+Normal recall and agent-scoped explain-recall also return the same `decisionTrace` contract:
+
+- `selectedLane`: `graph`, `compiled`, `brain_fallback`, `raw_ledger`, `mixed`, or `none`.
+- `reason`: a stable selection reason such as `compiled_cue_match`, `raw_cue_match_preferred`, or `no_recall_evidence`.
+- `candidateCounts`: bounded counts for graph, navigation, scoped navigation, brain fallback, and raw ledger lanes.
+- `selectedCount`: the number of returned items.
+
+OpenClaw renders this trace as one compact `recallDecision=` line inside the volatile recall block. It explains what Cogmem selected; it is not a user instruction or evidence. If the selected lane is `none`, inspect the query plan and run `cogmem explain-recall` before concluding that the memory does not exist.
+
+OpenClaw automatic injection wraps full recall evidence in `<COGMEM_RECALL_CONTEXT>`. That block is current-turn-only background memory, not current user intent and not raw ledger history. The wrapper strips it before recording turns. If the prompt also contains `<COGMEM_TURN_BRIDGE>` or `<COGMEM_SESSION_STATE>`, treat those as compact session sidecars for continuity only; re-run recall or inspect `sourceLocator` before relying on detailed evidence.
+
+For non-trivial recall, OpenClaw may prepend `<COGMEM_STRATEGY_CONTEXT>` before the recall block. This is a canonical current-turn retrieval policy, not evidence and not an instruction. It records the selected template, layer order, source policy, and budget. `cogmem_strategy_plan` exposes the same read-only capsule through MCP without performing recall. Normal MCP recall also returns `strategyCapsule`. If an exact-source strategy cannot find raw evidence, the bridge may make one narrowed retry; it must still report that source is unavailable rather than converting a summary into an exact quote.
+
+`--collection <name>` scopes recall to a named collection. Default recall only includes untagged and `collection:anchor` memory. Use `--collection theseus` for creative artifacts or drafts that should not enter normal operational recall.
+
+MCP `cogmem_recall` now uses this same agent-facing path. It returns `items` with `sourceType`, `sourceAnchor`, `sourceContext`, `canAnswerExactQuote`, and raw ledger fallback when governed compiled evidence is empty. If a host sends only `projectId`, MCP uses that value as `agentId` before falling back to `openclaw`. Hosts may also pass `collection`.
+
+Hookless hosts must also inspect recall warning metadata. `no_recent_episode_ingestion_detected` means Cogmem has not observed recent conversation traffic; `semantic_memory_may_lag` means open/soft-sealed high-value episodes, Dream backlog/failures, or recent raw evidence have not completed semantic curation. These warnings do not erase returned evidence, but the agent must append/import the missing messages or disclose that semantic freshness is uncertain before claiming memory is current.
+
+For past-memory queries such as `你还记得...`, a cue-matching raw user anchor outranks a compiled assistant retelling even when both contain the same topic words. The assistant retelling may remain as supporting evidence, but the original user event is first and retains its source locator.
+
+MCP `cogmem_explain_recall` is the audit tool. Like normal MCP recall, it derives `agentId` from `projectId` when the caller omits `agentId`. It reports the same selected evidence IDs and `decisionTrace` as agent recall, plus pulse, temporal, activation, and `filteredEvidence` details from `explainRecallWithKernel()`; use it to inspect why evidence was included or suppressed, not as a separate competing recall implementation.
+
+MCP `cogmem_memory_map` returns the memory self-map for agent/host inspection. MCP `cogmem_maintenance_tick` runs one explicit host-owned tick: activation decay plus suggested upkeep commands, with `hiddenDaemonStarted=false`.
+
+## Agent Query Plans
+
+`KernelAgentMemoryBackend.recall()` returns a `queryPlan` alongside agent-ready items. The plan records the original query, inferred/explicit intent, primary search text, bounded search cues, `semanticCuePhrases`, and `temporalHints` used for recall. This makes long questions auditable: an adapter can show that a sentence about "CogMem Memory Context 和记忆黑盒" was reduced to stable cues such as `CogMem Memory Context 记忆 黑盒`, `存档 黑盒`, or `黑盒` instead of being treated as one brittle raw string.
+
+If FTS cannot directly match a Chinese or mixed-language cue, raw fallback searches the fully scoped ledger instead of a fixed recent-event window. Scope filters still apply. Equal cue matches prefer the original user event, while `sourceContext.after` preserves the assistant reply for causal continuity; later assistant retellings do not displace the original anchor merely because they are longer.
+
+Forensic follow-ups can pass `anchorEventId` or `anchorText` from a previous recall item. The backend then prefers the anchored raw event for questions such as "what exactly did I say" instead of letting a vague query drift to unrelated imported summaries. Imported summaries and compiled memories still set `canAnswerExactQuote=false`; only raw source events with anchors can support exact wording.
+
+When an adapter can consume structured pre-answer context, call `KernelAgentMemoryBackend.recallPack()`. It wraps the normal recall result and adds:
+
+- `slots.direct`
+- `slots.associative`
+- `slots.entityCards`
+- `slots.beliefTouches`
+- `chargeVector`
+
+These slots are bounded and governed. They are meant for agent prompt assembly and host scheduling, not for unbounded graph traversal.
+
+## Dream Candidate Audit
+
+`raw_then_dream` makes episode and Dream backlog state visible before semantic compilation happens. `cogmem episode status` shows conversation boundaries, `cogmem dream tick` conditionally processes sealed episodes, and `cogmem memory candidates` shows the resulting governance queue. Open episodes are not Dream input.
+
+Each candidate includes:
+
+- `candidateType`: summary, preferences, user_preference, project_memory, long_term_goal, boundary, failure_lesson, diagnostic_conclusion, session_summary, topic_summary, temporal_fact_update, conflict_candidate, semantic_tags, indexing_decision, semantic_relation, edge_adjustment, contradictions, causalLinks, or another governed category.
+- `status`: usually `candidate` or `shadow` until a CPU governance policy reviews it.
+- `confidence`: a bounded extraction confidence, not truth confidence.
+- `content`: the proposed memory payload.
+- `evidence`: raw event anchors with `eventId`, role, global/thread order, parent/previous links, and source text excerpts.
+- `content.sourceEpisodeId`: the sealed conversation unit used for curation. It is an audit pointer, not evidence by itself.
+
+Candidates explain organization, not truth. A preference candidate can show that the user explicitly said a constraint, but it is still queued for governance. A tool-result causal candidate can show that one tool result belongs to a tool call, but it must not become a verified real-world fact merely because the tool returned text.
+
+An explicit user clarification may produce an organizational `correction` candidate. It does not automatically produce a contradiction or rewrite a belief. `CorrectionResolver` must bind it to an active same-project claim/belief; orphan or ambiguous corrections stay `needs_confirmation` with `orphan_correction_requires_target_review`. Assistant apologies/self-corrections and negative-form user questions are not sufficient user-owned correction evidence. A provider candidate must cite exact current episode event IDs; `["all"]`, unknown IDs, and fallback to unrelated leading events are rejected. Provider project labels cannot override CPU-owned project scope.
+
+Semantic organization candidates are also advisory. `semantic_tags` and `indexing_decision` can make future recall less brittle than full-sentence matching, while `semantic_relation` and `edge_adjustment` can propose local graph activation changes. They do not rewrite existing memories or promote facts by themselves.
+
+When `[memory_model]` is configured, the worker may call a local Ollama or cloud OpenAI-compatible memory model to propose richer candidates. The explainability contract is unchanged: model output must include source evidence, remains candidate-only, and cannot directly change active memory.
+
+## Filtered Evidence
+
+`filteredEvidence` records same-project candidates that were considered but did not enter active context. Reasons include:
+
+- `status_suppressed`
+- `over_context_limit`
+- `agent_scope_mismatch`
+- `collection_scope_mismatch`
+
+When available, filtered evidence also carries `sourceAnchor` so forensic tools can explain where a suppressed candidate came from. Scoped explain results must stay same-project; cross-project filtered evidence must not be exposed.
+
+## Ledger Vs Recall
+
+Use chronological ledger APIs when the question is about original order:
+
+- `getThreadEvents(threadId)`
+- `getEventContext(eventId, { before, after })`
+
+Use governed recall when the agent needs current task context:
+
+- `KernelAgentMemoryBackend.recall()`
+- `MemoryKernel.navigateMemory()`
+- `explainRecallWithKernel()`
+
+Use the local audit CLI when the user needs to inspect memory directly:
+
+- `cogmem memory status`
+- `cogmem memory list`
+- `cogmem memory search --query <text>`
+- `cogmem memory recall --query <text> --agent <agent>`
+- `cogmem memory show --event <eventId> --before 2 --after 2`
+- `cogmem episode status --project <project>`
+- `cogmem dream tick --project <project> --mode auto`
+- `cogmem memory candidates --project <project> --status candidate`
+- `cogmem memory candidates --project <project> --status needs_confirmation`
+- `cogmem memory review --project <project> --id <candidateId> --action <approve|reject|defer|supersede|relink> --actor <operator> --reason <reason>`
+- `cogmem memory map --project <project> --json`
+- `cogmem memory tick --project <project> --json`
+
+Ledger replay can show raw evidence. It must not replace governed recall, pulse activation, inhibition, or ContextPack budgeting.
+## Memory Atlas versus direct recall
+
+Use Memory Atlas before direct recall when the user asks what is remembered, asks a broad project/history question, or needs relationships between multiple memory areas. Use direct recall for a concrete factual question. Atlas narrows the search space; it does not answer from summaries alone.
+
+The expected sequence is `graphExplore` or `graphSearch`, then `graphNode`/`graphPath`/`graphTimeline`, then exact Raw Ledger drill-down. Atlas evidence includes `eventId` and a `cogmem memory show` command. Raw excerpts are omitted unless `includeEvidence=true`.
+
+`coldMemoryResurrected=true` means query facets surfaced a low-activation node. It is a ranking explanation, not proof that the node is true or newly promoted. Inspect the node status, confidence, and raw source before making a claim.
+
+Atlas query tools are read-only and do not change activation. If the agent actually uses a returned node, MCP `cogmem_graph_touch` records that selected-node use separately. Evidence output distinguishes the node's full `evidenceTotal` from the bounded `evidenceReturned` payload.

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,92 @@
+# cogmem 3.6.2 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.6.2`.
+- `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.
+- `install.sh` is tracked and installs `cogmem@latest` from npm by default.
+- Local databases, SQLite sidecars, `.DS_Store`, and `dist/.tsbuildinfo` are not tracked.
+
+## Required Binaries
+
+- `cogmem`
+- `cogmem init`
+- `cogmem doctor`
+- `cogmem connect`
+- `cogmem update`
+- `cogmem openclaw diagnose`
+- `cogmem-compact`
+- `cogmem memory`
+- `cogmem repair`
+- `cogmem explain-recall`
+- `cogmem-mcp`
+- `cogmem import-openclaw`
+- `cogmem import-hermes`
+- `cogmem normalize-transcript`
+- `cogmem snapshot`
+- `cogmem re-embed`
+- `cogmem migrate-vectors`
+- `cogmem migrate`
+- `cogmem prospective`
+- `cogmem strategy`
+- `cogmem brain-eval`
+- `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.
+
+## Required Documentation
+
+- README explains the vision, architecture, limits, and one-line install command.
+- README says this is a single-agent memory kernel, not an agent team shared brain.
+- README distinguishes embedding models from Dream Curator memory-model LLMs.
+- README and integration docs explain labeled `sourceContext`, strict before/after window metadata, `charRange` / `sourceRange`, and OpenClaw `sourceWindow` / `sourceTruncation` injection.
+- README and skills explain collection routing, `cogmem memory map`, and `cogmem memory tick` as host-owned inspection and maintenance surfaces.
+- README and skills explain `decisionTrace` / `recallDecision`, source-first raw fallback, correction semantics, audited review actions, and review-queue aging.
+- README and skills explain `cogmem update --yes`, npm install resolution, automatic backed-up migration, automatic OpenClaw plugin-only refresh when configured, migration dry-run, backups, and that Raw Ledger evidence is never rewritten by schema migration.
+- README and skills explain that entity aliases are evidence-backed, project-scoped, reversible, and stricter for person entities.
+- README and skills explain Belief Graph ownership, user-evidence requirements, reinforcement, conflict review, and supersession history.
+- README and skills explain Temporal Memory validity windows, historical lookup, correction reasons, and current-state stale suppression.
+- README and skills explain Context Cortex intent suppression, 25% default/30% maximum budget, source drill-down, and activation receipts.
+- README and skills explain that Prospective Memory is confirmed-only state with no task execution capability, and how to use BrainEval as a release gate.
+- README and skills explain Strategy Cortex templates, no-instruction-authority lifecycle, one-retry replanning, strategy-conditioned retrieval, offline-only rollout comparison, and read-only MemoryUseJudge telemetry.
+- 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 explain CPU foreground versus hybrid background classification, contextual short replies, registry-aware topic boundaries, safe reopen, semantic-summary non-evidence status, per-job Dream modes/failures, stable import identity, and schema migration 24.
+- README and skills explain user-shaped topic operations, user-explicit versus model-candidate authority, alias collision review, operation rollback, and project isolation.
+- README, `MEMORY_ATLAS.md`, and skills distinguish the system anatomy map from the content Atlas; explain graph overview/search/explore/node/neighbors/path/timeline, generic multi-facet cold-memory resurrection, activation visibility, source drill-down, and project isolation.
+- README documents `cogmem.cli.v1`: object payloads are top-level, array payloads use `items`, and queue counters expose top-level compatibility aliases.
+- README documents the one-line schema-24/schema-26/pre-release schema-25 to schema-27 migration with backup, and migration tests prove source counts are preserved, Atlas projection is dirty after upgrade, and reruns are idempotent.
+- README and OpenClaw skill document plugin-only repair, plugin/audit diagnose, stale graph reads, and conservative empty-project project-scope repair for 3.5.2 -> 3.6.x upgrades.
+- README and skills explain episode surgery, closure recomputation, stale-candidate invalidation, cross-reference/audit preservation, and sealed-only Dream requeue.
+- README and Hermes skill explain per-message import checkpoints, stable `externalMessageId` requirements across split batches, source-agent validation, CLI range/error controls, and hookless recall freshness warnings.
+- OpenClaw installation includes `SKILL.md` plus the complete `references/operations.md` command handbook covering migration, import, review, Atlas, repair, backup, and maintenance.
+- Hermes installation includes the same complete handbook, MCP wiring, `connect hermes --auto`, and `/reload-mcp`.
+- OpenClaw skill explains the direct plugin Atlas route without MCP; Hermes skill explains graph-first MCP tool selection and exact evidence drill-down.
+- BrainEval fixtures cover Atlas scope isolation, traversal bounds, evidence locators, path reconstruction, faceted resurrection, and canonical-source immutability.
+- Concurrency fixtures prove read-only inspection while another connection is open; Atlas fixtures prove pure reads, explicit touch, dirty-only rebuild, error state, retention, weighted path, and exact facet composition.
+- SECURITY documents local-first storage, explicit external providers, snapshots as sensitive, and governed recall.
+
+## Verification
+
+Run from the repository root:
+
+```bash
+bun run typecheck
+bun run build
+bun test
+npm pack --dry-run --json
+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, publish with:
+
+```bash
+npm publish --access public
+```

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security
+
+`cogmem` is local-first by default. Memory data is stored in the configured SQLite database path.
+
+## Data Handling
+
+- Core does not require a hosted storage service.
+- TOML is the only kernel configuration entrypoint. Security and governance settings live in `config.toml`; environment variables are only interpolated when explicitly referenced in that file.
+- PII redaction is configured under `[governance]` with `pii_redact_email`, `pii_redact_phone`, and `pii_redact_ssn`.
+- Field encryption is available by passing an `EncryptionProvider` when creating the kernel.
+- Embedding providers may send text to the provider explicitly configured in `config.toml`.
+- Snapshot files should be treated as sensitive because they contain exported memory data.
+- Imports and migrations should be run with dry-run first when moving existing agent memory into core.
+- Raw chronological ledger events are written through the kernel so configured PII redaction runs before persistence. Encrypted deployments still treat ledger payloads as sensitive.
+- Agent-facing recall is governed by default: archived memory, suspect LLM inference, suspect tool observations, and suspect unverified claims are suppressed from active context.
+- Raw user utterances can be recalled as provenance evidence when explicitly tagged as raw user evidence; this does not promote them into verified facts.
+- Recall explanations expose same-project `filteredEvidence` with `reason` and optional `governanceReason`. Scoped explanations must not expose filtered evidence from other projects.
+
+## Reporting
+
+Report vulnerabilities privately through the repository security advisory flow. Do not open public issues for exploitable security bugs.

package/dist/adapters/MarkdownSourceLoader.d.ts

@@ -0,0 +1,5 @@
+import type { SourceDefinition, SourceFileSnapshot } from './types.js';
+export declare class MarkdownSourceLoader {
+    read(source: SourceDefinition): SourceFileSnapshot;
+}
+//# sourceMappingURL=MarkdownSourceLoader.d.ts.map

package/dist/adapters/MarkdownSourceLoader.js

@@ -0,0 +1,19 @@
+import { readFileSync, statSync } from 'node:fs';
+import { computeStableHash } from './types.js';
+export class MarkdownSourceLoader {
+    read(source) {
+        const stat = statSync(source.sourcePath);
+        const content = source.adapterKind === 'hermes_state_db' ? '' : readFileSync(source.sourcePath, 'utf8');
+        return {
+            sourceId: source.sourceId,
+            adapterKind: source.adapterKind,
+            sourcePath: source.sourcePath,
+            projectId: source.projectId,
+            fileHash: computeStableHash([source.sourcePath, stat.mtimeMs, stat.size, content]),
+            fileMtimeMs: stat.mtimeMs,
+            fileSize: stat.size,
+            readAt: Date.now(),
+            content
+        };
+    }
+}

package/dist/adapters/conversation/ConversationMarkdownAdapter.d.ts

@@ -0,0 +1,9 @@
+import type { AdaptedSource, AdapterWindow, SourceAdapter, SourceDefinition, SourceFileSnapshot } from '../types.js';
+export declare class ConversationMarkdownAdapter implements SourceAdapter {
+    readonly kind: "conversation_markdown";
+    private readonly adapterVersion;
+    adapt(source: SourceDefinition, snapshot: SourceFileSnapshot, window?: AdapterWindow): AdaptedSource;
+    private parseMessages;
+    private buildRecords;
+}
+//# sourceMappingURL=ConversationMarkdownAdapter.d.ts.map

package/dist/adapters/conversation/ConversationMarkdownAdapter.js

@@ -0,0 +1,233 @@
+import { computeStableHash, inferSourceTitle, normalizeMarkdownText, parseLooseDateHeading, parseMarkdownRoleLine, resolveTimestampWithContext } from '../types.js';
+export class ConversationMarkdownAdapter {
+    kind = 'conversation_markdown';
+    adapterVersion = 'conversation-markdown-v2';
+    adapt(source, snapshot, window) {
+        const normalized = normalizeMarkdownText(snapshot.content);
+        const lines = normalized.split('\n');
+        const diagnostics = [];
+        const messages = this.parseMessages(lines, snapshot.fileMtimeMs, source.sourcePath, diagnostics);
+        const filteredMessages = messages.filter((message) => !window || (message.timestamp >= window.start && message.timestamp < window.end));
+        const records = this.buildRecords(source, snapshot, filteredMessages);
+        return {
+            source,
+            snapshot: {
+                sourceId: snapshot.sourceId,
+                adapterKind: snapshot.adapterKind,
+                sourcePath: snapshot.sourcePath,
+                projectId: snapshot.projectId,
+                fileHash: snapshot.fileHash,
+                fileMtimeMs: snapshot.fileMtimeMs,
+                fileSize: snapshot.fileSize,
+                readAt: snapshot.readAt
+            },
+            records,
+            diagnostics
+        };
+    }
+    parseMessages(lines, fallbackTime, sourcePath, diagnostics) {
+        const messages = [];
+        let current = null;
+        let currentDateHint;
+        let currentSessionStartedAt;
+        let pendingSourceRef;
+        let ignoredPrelude = 0;
+        let collapsedAdjacentDuplicates = 0;
+        const flush = () => {
+            if (!current)
+                return;
+            const text = current.text.trim();
+            if (text) {
+                const lineSpan = Math.max(1, text.split('\n').length);
+                const message = { ...current, text, lineEnd: current.lineNumber + lineSpan - 1 };
+                const previous = messages[messages.length - 1];
+                if (previous && previous.role === message.role && previous.text === message.text) {
+                    collapsedAdjacentDuplicates += 1;
+                }
+                else {
+                    messages.push(message);
+                }
+            }
+            current = null;
+        };
+        lines.forEach((line, index) => {
+            const sourceRefMarker = parseSourceRefMarker(line);
+            if (sourceRefMarker) {
+                pendingSourceRef = sourceRefMarker;
+                return;
+            }
+            if (/^<!--\s*cogmem-[a-z0-9_-]+:/i.test(line.trim()) || /^<!--\s*cogmem-normalized\s*:/i.test(line.trim())) {
+                return;
+            }
+            const sessionStartedAt = parseSessionStartedAt(line);
+            if (sessionStartedAt !== undefined) {
+                currentSessionStartedAt = sessionStartedAt;
+                currentDateHint = new Date(sessionStartedAt).toISOString().slice(0, 10);
+                return;
+            }
+            const dateHeading = parseLooseDateHeading(line);
+            if (dateHeading) {
+                currentDateHint = dateHeading;
+                currentSessionStartedAt = undefined;
+                return;
+            }
+            const parsed = parseMarkdownRoleLine(line);
+            if (parsed) {
+                flush();
+                current = {
+                    role: parsed.role,
+                    text: parsed.text,
+                    timestamp: parsed.timestamp
+                        ? resolveTimestampWithContext(parsed.timestamp, fallbackTime + index, currentDateHint)
+                        : (currentSessionStartedAt ?? fallbackTime) + index,
+                    lineNumber: index + 1,
+                    lineEnd: index + 1,
+                    sourceRef: pendingSourceRef,
+                };
+                pendingSourceRef = undefined;
+                return;
+            }
+            if (!current) {
+                if (line.trim())
+                    ignoredPrelude += 1;
+                return;
+            }
+            current.text += `${current.text ? '\n' : ''}${line.trimEnd()}`;
+        });
+        flush();
+        if (collapsedAdjacentDuplicates > 0) {
+            diagnostics.push({
+                severity: 'warning',
+                code: 'conversation_adjacent_duplicate_collapsed',
+                message: `Collapsed ${collapsedAdjacentDuplicates} adjacent exact duplicate message(s).`,
+                filePath: sourcePath,
+                adapterKind: this.kind,
+                contractHint: 'Adjacent messages with the same role and identical normalized text are treated as export duplicates.',
+                fallbackHint: 'Non-adjacent repeated messages remain separate chronological evidence.',
+            });
+        }
+        if (messages.length === 0 && lines.some((line) => line.trim())) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'conversation_contract_mismatch',
+                message: 'No parseable conversation messages were found.',
+                filePath: sourcePath,
+                adapterKind: this.kind,
+                contractHint: 'Expected role-prefixed transcript lines such as "user:", "Human:", "Q:", "AI:", or "assistant:".',
+                fallbackHint: 'Use repeated --conversation only for transcript-style files, or minimally normalize the markdown into role-prefixed lines before ingestion.'
+            });
+        }
+        else if (ignoredPrelude > 0) {
+            diagnostics.push({
+                severity: 'warning',
+                code: 'conversation_partial_prelude_ignored',
+                message: `Ignored ${ignoredPrelude} non-message line(s) before the first parseable transcript turn.`,
+                filePath: sourcePath,
+                adapterKind: this.kind,
+                contractHint: 'Intro headings and date headers are tolerated, but only role-prefixed transcript lines become episodic records.',
+                fallbackHint: 'If important turns live outside the transcript shape, move them into explicit role-prefixed lines or ingest the file through --soul instead.'
+            });
+        }
+        return messages;
+    }
+    buildRecords(source, snapshot, messages) {
+        const sourceTitle = inferSourceTitle(source.sourcePath);
+        const records = [];
+        let turnCursor = 0;
+        let openTurnId;
+        let lastRole;
+        let eventOrdinal = 0;
+        for (const message of messages) {
+            if (!openTurnId || message.role === 'user' || (lastRole === 'agent' && message.role !== 'agent')) {
+                turnCursor += 1;
+                eventOrdinal = 0;
+                openTurnId = computeStableHash([source.sourceId, snapshot.fileHash, 'turn', turnCursor]);
+            }
+            eventOrdinal += 1;
+            const sourceOffset = message.sourceRef?.sourceOffset ?? records.length + 1;
+            const lineStart = message.sourceRef?.lineStart ?? message.lineNumber;
+            const lineEnd = message.sourceRef?.lineEnd ?? message.lineEnd;
+            const orderingConfidence = message.sourceRef?.orderingConfidence ?? 'high';
+            const recordHash = computeStableHash([
+                source.sourceId,
+                message.role,
+                message.timestamp,
+                message.text
+            ]);
+            records.push({
+                recordId: `srcmsg-${recordHash.slice(0, 16)}`,
+                turnId: openTurnId,
+                kind: 'conversation_message',
+                role: message.role,
+                text: message.text,
+                timestamp: message.timestamp,
+                tags: [sourceTitle, 'conversation'],
+                confidenceHint: 0.92,
+                sourceTypeHint: message.role === 'agent' ? 'llm_inference' : 'user_input',
+                metadata: {
+                    lineNumber: message.lineNumber,
+                    lineStart,
+                    lineEnd,
+                    charStart: message.sourceRef?.charStart,
+                    charEnd: message.sourceRef?.charEnd,
+                    sourceOffset,
+                    turnIndex: turnCursor,
+                    turnSeq: turnCursor,
+                    eventOrdinal,
+                    orderingConfidence
+                },
+                provenance: {
+                    sourceId: source.sourceId,
+                    sourcePath: source.sourcePath,
+                    sourceType: this.kind,
+                    adapterVersion: this.adapterVersion,
+                    fileHash: snapshot.fileHash,
+                    fileMtimeMs: snapshot.fileMtimeMs,
+                    recordHash,
+                    reliabilityClass: 'raw_utterance',
+                    lineStart,
+                    lineEnd,
+                    charStart: message.sourceRef?.charStart,
+                    charEnd: message.sourceRef?.charEnd,
+                    sourceOffset,
+                    orderingConfidence
+                }
+            });
+            lastRole = message.role;
+        }
+        return records;
+    }
+}
+function parseSessionStartedAt(line) {
+    const heading = line.trim().replace(/^#{1,6}\s*/, '');
+    const match = heading.match(/^Session\s*:\s*(.+)$/i);
+    if (!match?.[1])
+        return undefined;
+    const parsed = Date.parse(match[1].trim());
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+function parseSourceRefMarker(line) {
+    const match = line.trim().match(/^<!--\s*(?:cogmem|agent-brain)-source-ref:\s*([^]+?)\s*-->$/i);
+    if (!match?.[1])
+        return undefined;
+    try {
+        const parsed = JSON.parse(match[1].replace(/--&gt;/g, '-->'));
+        return {
+            sourceOffset: numberField(parsed.sourceOffset),
+            lineStart: numberField(parsed.lineStart),
+            lineEnd: numberField(parsed.lineEnd),
+            charStart: numberField(parsed.charStart),
+            charEnd: numberField(parsed.charEnd),
+            orderingConfidence: orderingConfidenceField(parsed.orderingConfidence),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function numberField(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function orderingConfidenceField(value) {
+    return value === 'high' || value === 'medium' || value === 'low' ? value : undefined;
+}

package/dist/adapters/hermes/HermesStateDbAdapter.d.ts

@@ -0,0 +1,10 @@
+import type { AdaptedSource, AdapterWindow, SourceAdapter, SourceDefinition, SourceFileSnapshot } from '../types.js';
+export declare class HermesStateDbAdapter implements SourceAdapter {
+    readonly kind: "hermes_state_db";
+    private readonly adapterVersion;
+    adapt(source: SourceDefinition, snapshot: SourceFileSnapshot, window?: AdapterWindow): AdaptedSource;
+    private toRecord;
+    private result;
+    private diagnostic;
+}
+//# sourceMappingURL=HermesStateDbAdapter.d.ts.map