Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Session-import orchestrator (§16).
*
* Public surface:
*
* - {@link importSession} — single-file import. Returns per-file
* counters and the resolved adapter id.
* - {@link importSessionPath} — convenience wrapper that walks a
* directory, calling importSession on every `*.jsonl` inside.
* Files whose autodetect fails surface as `warnings` rather than
* killing the run; valid files still get processed.
*
* Extraction pipeline per turn:
*
* 1. `discoverMarkers(turn.text)` → for each marker, build a
* payload via {@link computeDedupHash}; create a signal with
* `source_type: 'session'` unless the hash already exists in
* `Brain/inbox/` or `processed/`.
* 2. For each `tool_use` block named `brain_feedback`: validate
* input via {@link validateBrainFeedbackInput}, compute the
* same hash; dedup-check; create signal.
*
* Mined mentions (recall-quality, B1) ride the same loop: admitted
* turns of either role are scanned by {@link mineAndRecordTurn} while
* the raw text still exists, folding one `session_entity_mention`
* continuity record per (family, key, session). Provenance-grade only -
* nothing here writes an entity page.
*
* Idempotency: dedup index is built once at the start of each
* `importSession` run by reading the inbox and processed dirs. A
* second run on the same file finds every hash already present.
*
* Resume (nothing-writes-silently, Unit F). Dedup alone is
* re-do-and-discard: it makes a second run harmless, not cheap, so an
* interrupted 50k-turn import re-read and re-hashed every turn to
* conclude it had nothing to write. An applied run now records the turn
* boundary it has reached into {@link ./checkpoint.ts} - the sessions
* lane's extension of the ingest checkpoint substrate, not a second one
* of its own - and the next run over the same file with the same filters
* skips straight past those turns. What that saves is the extraction
* work: the marker scan, the dedup hashing, the fact pass and the writes.
* The lines themselves are still read, because a JSONL transcript has no
* index to seek into.
*
* Recall is the one thing the boundary does not vouch for, and the resumed
* run re-collects it. `--recall` accumulates turns in memory and commits
* them to the recall DAG AFTER the loop, so a run that stopped at the
* boundary committed none of them; skipping those turns on the resumed run
* would leave the head of the transcript permanently missing from the DAG
* while both runs reported success. Re-collection costs nothing extra (the
* lines are read regardless) and is idempotent, because the recall importer
* keys every turn on a content dedupe key.
*
* Census (same unit). After the run, the dedup hashes of the signals it
* claims to have written are read back from disk, and the result carries
* `claimed / found / missing` with the missing hashes NAMED. See
* {@link ../import-census.ts} for what the census does and does not cover.
*/
import { existsSync, statSync } from "node:fs";
import { basename, resolve } from "node:path";
import { delegatedAgentName } from "../../agent-identity.ts";
import { readSkillOfferId, SKILL_OFFER_ID_KEY } from "../../surface/skill-offer.ts";
import { checkpointingEnabled } from "../checkpoint-store.ts";
import { computeDedupHash, loadDedupIndex, type DedupIndexEntry } from "../dedup-hash.ts";
import { censusSessionSignals, type ImportCensus } from "../import-census.ts";
import { appendContinuityRecord } from "../continuity/store.ts";
import { discoverMarkersDetailed, isFeedbackMarker } from "../inline.ts";
import { writeSignal } from "../signal.ts";
import { stampPromptDerivedLine } from "../provenance/content-class.ts";
import { importSessionRecall } from "../session-recall.ts";
import { isoDate, isoSecond } from "../time.ts";
import { BRAIN_SIGNAL_SOURCE_TYPE } from "../types.ts";
import {
clearSessionCheckpoint,
computeSessionHeadHash,
computeSessionImportId,
recordSessionProgress,
resolveSessionResume,
SESSION_CHECKPOINT_TURN_INTERVAL,
type SessionResumeDiscard,
} from "./checkpoint.ts";
import { readFirstLine } from "./read-lines.ts";
import { detectAdapter, getAdapter } from "./registry.ts";
import { sessionFilesUnder } from "./session-files.ts";
import {
SessionImportError,
type SessionAdapter,
type SessionAdapterId,
type SessionToolCall,
type SessionTurn,
} from "./types.ts";
import { validateBrainFeedbackInput } from "./validate-feedback.ts";
import { buildCaptureBoundary, type SessionCaptureDecision } from "../capture-boundary.ts";
import { emitIngestDedupReport } from "../dedup-telemetry.ts";
import { extractFacts, routeExtractedFacts } from "../fact-extract.ts";
import { mineAndRecordTurn } from "../link-graph/session-mining.ts";
import { readLineageLedger } from "../lineage/ledger.ts";
import { resolveSessionLineage } from "../lineage/resolve.ts";
import type { SessionLineage } from "../lineage/types.ts";
export interface ImportSessionOptions {
/** Agent identity stamped on signals when the turn has no own agent. */
readonly agent: string;
/** Force a specific adapter, bypassing autodetect. */
readonly format?: SessionAdapterId;
/** ISO timestamp — process only turns at or after this. */
readonly since?: Date;
/** When true, don't write any signal. Counters still populate. */
readonly dryRun?: boolean;
/** Wall clock for stamping `created_at`. Tests pin this. */
readonly now?: Date;
/**
* Optional pre-built dedup index. When importing a directory of
* session files, the orchestrator builds the index once and
* threads it through every per-file call so the inbox isn't
* re-scanned per file. Internal contract; CLI does not pass it.
*/
readonly dedupIndex?: Map<string, DedupIndexEntry>;
/**
* Vault portability suite (v0.22.0). When true, session-imported
* signals store their raw body through the deterministic codec
* (`writeSignal({ rawCodec: true })`). Default off -> verbatim bodies.
*/
readonly rawCodec?: boolean;
/** When true, also store normalized turns in the continuity-backed session recall DAG. */
readonly recall?: boolean;
readonly recallSessionId?: string;
readonly recallSummaryGroupSize?: number;
/**
* Lineage of the imported segment (continuity-hygiene-freshness
* suite). When omitted, a link persisted in the lineage ledger for
* the recall session id is used; flat sessions import unchanged.
*/
readonly recallLineage?: SessionLineage;
/** Optional ingest scope label stamped into imported signal notes. */
readonly ingestScope?: string;
/** Optional role filter for write-side extraction. */
readonly filterRoles?: ReadonlyArray<SessionTurn["role"]>;
/** Optional case-insensitive substring filter on turn text. */
readonly filterTextIncludes?: string;
/**
* Per-row event-time backfill (A2 / t_7526e8d3). When true, each
* emitted signal is stamped with its turn's ORIGINAL
* `SessionTurn.timestamp` (`created_at` / `recorded_at` / `valid_from`
* and the filename calendar day) instead of the import wall-clock, so
* backfilling an old session log stays historically faithful and
* recency-based reconciliation can trust the timestamps. A turn whose
* timestamp is absent, unparseable, at/before the Unix epoch (the
* adapter's "no timestamp" sentinel), or future-dated relative to
* `now` falls back to `now` deterministically — no throw, no
* future-dated or epoch signal. Default off → byte-identical to the
* wall-clock path.
*/
readonly preserveEventTime?: boolean;
}
/**
* Resolve the effective stamp instant for an emitted signal under the
* per-row event-time backfill (A2). Returns whether the instant came
* from the turn (so the caller stamps the bi-temporal slots) or fell
* back to `now` (so the file stays byte-identical to the wall-clock
* path — no `recorded_at` / `valid_from` keys).
*
* The usable window is `epoch < ts <= now`: a timestamp at or before the
* Unix epoch is the adapter's synthesized "no timestamp" sentinel
* (`new Date(0)`), a future timestamp would mint a nonsensical
* forward-dated signal during backfill, and an unparseable value is
* `NaN` — all three fall back to `now`.
*/
export function resolveEventInstant(
turnTimestamp: string | undefined,
now: Date,
preserve: boolean,
): { readonly instant: Date; readonly fromTurn: boolean } {
if (!preserve || !turnTimestamp) return { instant: now, fromTurn: false };
const ms = Date.parse(turnTimestamp);
if (!Number.isFinite(ms) || ms <= 0 || ms > now.getTime()) {
return { instant: now, fromTurn: false };
}
return { instant: new Date(ms), fromTurn: true };
}
/**
* Whether an import's counters describe writes that HAPPENED or writes it
* would have made. A dry run's `signals_created` is zero by construction,
* which is also what a real run over a session with nothing in it reports;
* without this the two results are the same bytes.
*/
export const IMPORT_WRITE_MODE = Object.freeze({
applied: "applied",
dryRun: "dry_run",
} as const);
export type ImportWriteMode = (typeof IMPORT_WRITE_MODE)[keyof typeof IMPORT_WRITE_MODE];
export const IMPORT_WRITE_MODES: ReadonlyArray<ImportWriteMode> = Object.freeze([
IMPORT_WRITE_MODE.applied,
IMPORT_WRITE_MODE.dryRun,
]);
export function isImportWriteMode(value: unknown): value is ImportWriteMode {
return typeof value === "string" && (IMPORT_WRITE_MODES as ReadonlyArray<string>).includes(value);
}
export interface ImportSessionResult {
readonly file: string;
/** Id of the adapter that parsed the file; a registry key, not a union. */
readonly format: string;
/** Whether the counters below describe writes made or writes forecast. */
readonly write_mode: ImportWriteMode;
readonly turns_scanned: number;
readonly signals_created: number;
/**
* Signals a dry run would have written. Always 0 under
* {@link IMPORT_WRITE_MODE.applied} - a real run writes instead of
* withholding - so the pair (`signals_created`, `signals_withheld`) says
* which run this was and what it did in one reading.
*/
readonly signals_withheld: number;
readonly signals_deduped: number;
readonly tool_replays: number;
/** Per-skill invocations captured as skill_invoked continuity records. */
readonly skill_invocations: number;
readonly malformed: number;
readonly filtered_turns: number;
/** Capture-boundary verdict for this file (Memory Integrity Suite). */
readonly boundary_decision: SessionCaptureDecision;
/** Turns whose text was suppressed before any extraction. */
readonly suppressed_turns: number;
readonly facts_extracted: number;
/** Facts a dry run would have written. Always 0 on an applied run. */
readonly facts_withheld: number;
readonly facts_deduped: number;
/**
* Facts the ambient extraction lane withheld whole captures of, because
* `guardrails.ambient_writeback: false` is in force (Task 11). Each
* suppressed capture also logs one `ambient-withheld` event carrying the
* same count, so a consent-off import reports 0 facts written AND the
* count it declined to capture - never a silent zero.
*/
readonly facts_ambient_withheld: number;
/**
* Mined-mention records the session-mining lane wrote (recall-quality,
* B1): one continuity record per (family, key, sessionRef), folded
* across the run. Provenance-grade only - nothing here mints an entity
* page; promotion is a separate, explicit step.
*/
readonly mined_extracted: number;
/** Mentions already folded for this (family, key, session) this run. */
readonly mined_deduped: number;
/** Mentions a dry run would have written. Always 0 on an applied run. */
readonly mined_withheld: number;
/** Secret-shaped candidates (credential URLs, token forms) refused. */
readonly mined_secret_refused: number;
/** Turns carrying a private region, withheld whole from mining. */
readonly mined_private_withheld: number;
/**
* Mentions whose ledger append THREW this run - the miner's telemetry-grade
* tolerance keeps the import alive, and this slot carries the failure past
* `mineAndRecordTurn`'s `ledgerFailed` outcome so no import surface can
* report a clean run over a ledger it could not write. A failed mention
* stays unseen, so the next import re-folds it.
*/
readonly mined_ledger_failed: number;
/**
* Mentions dropped because a session already holds the miner's
* `MAX_MINED_KEYS_PER_SESSION` (512) distinct keys - the cap
* `mineAndRecordTurn` enforces, surfaced here through its `capOverflow`
* outcome so an over-cap import reports the overflow instead of a quietly
* truncated mention set.
*/
readonly mined_cap_overflow: number;
readonly recall_turns_imported: number;
readonly recall_summary_nodes: number;
/**
* Turns a checkpoint from an earlier, interrupted run let this one skip.
* Always 0 on a first run, a dry run, and a run with checkpointing opted
* out. `turns_scanned` still counts every turn the adapter yielded, so the
* pair says how much of the file was re-read and how little was re-worked.
*/
readonly turns_resumed: number;
/**
* Why a checkpoint that existed was NOT resumed from, or `null` when none
* was refused. A boundary silently ignored is a full re-import nobody was
* told about, which is the class of quiet this unit removes.
*/
readonly resume_discarded: SessionResumeDiscard | null;
/**
* Read-back census of the signals this run claims to have written:
* `attempted / found / missing`, with the missing dedup hashes named. A
* dry run claims nothing and censuses zero.
*/
readonly census: ImportCensus;
readonly errors: ReadonlyArray<{ path: string; message: string }>;
}
export interface ImportSessionPathResult {
readonly files: ReadonlyArray<ImportSessionResult>;
/** Per-file warnings (autodetect failures, IO errors). */
readonly warnings: ReadonlyArray<{ path: string; message: string }>;
}
/**
* Portable session identity for provenance refs (Vault portability suite).
*
* A session file's absolute path is machine-local, so persisting it into a
* synced signal's `source` / `session_ref` bakes in a host path (e.g.
* `/root/vault/...` vs a Mac/Android home) that no Syncthing peer can
* resolve. We key provenance by the session file's basename instead — the
* same identity the recall DAG uses — so signal provenance and recall
* records join on one portable id. An explicit `recallSessionId` wins so a
* caller can pin a stable logical id.
*/
export function sessionRefIdentity(absPath: string, recallSessionId?: string): string {
const explicit = recallSessionId?.trim();
return explicit && explicit.length > 0 ? explicit : basename(absPath);
}
/**
* Pick an adapter — by explicit format, or autodetect.
*
* Autodetect needs exactly one line, and `readFirstLine` stops at the first
* newline: the file used to be read whole here and then read a second time by
* `adapter.iterate`. An explicit `--format` reads nothing at all - hence the
* lazy `readHead`, shared with the resume checkpoint's file-identity probe so
* the head line is read at most once per import and not at all when neither
* caller needs it.
*/
async function chooseAdapter(
path: string,
readHead: () => Promise<string>,
format?: SessionAdapterId,
): Promise<SessionAdapter> {
if (format !== undefined) {
return getAdapter(format);
}
const first = await readHead();
const a = detectAdapter(first);
if (!a) {
throw new SessionImportError(
"DETECT_FAIL",
`could not autodetect session format for ${path}; pass --format to override`,
);
}
return a;
}
export async function importSession(
vault: string,
path: string,
opts: ImportSessionOptions,
): Promise<ImportSessionResult> {
if (!existsSync(path)) {
throw new SessionImportError("IO", `session file does not exist: ${path}`);
}
let headLine: string | null = null;
const readHead = async (): Promise<string> => (headLine ??= await readFirstLine(path));
const adapter = await chooseAdapter(path, readHead, opts.format);
// Reuse the caller-supplied index when present (directory walk lifts
// the build out of the per-file loop). Otherwise build our own.
const dedup = opts.dedupIndex ?? (await loadDedupIndex(vault));
const now = opts.now ?? new Date();
const sinceMs = opts.since ? opts.since.getTime() : undefined;
const absPath = resolve(path);
// Portable provenance key for signal/fact `source` + `session_ref` and the
// recall DAG id — never the machine-local `absPath`. See sessionRefIdentity.
const sessionKey = sessionRefIdentity(absPath, opts.recallSessionId);
const errors: { path: string; message: string }[] = [];
const writeMode = opts.dryRun === true ? IMPORT_WRITE_MODE.dryRun : IMPORT_WRITE_MODE.applied;
let turnsScanned = 0;
let signalsCreated = 0;
let signalsWithheld = 0;
let signalsDeduped = 0;
let toolReplays = 0;
let skillInvocations = 0;
let malformed = 0;
let filteredTurns = 0;
let suppressedTurns = 0;
let factsExtracted = 0;
let factsWithheld = 0;
let factsDeduped = 0;
let factsAmbientWithheld = 0;
let minedExtracted = 0;
let minedDeduped = 0;
let minedWithheld = 0;
let minedSecretRefused = 0;
let minedPrivateWithheld = 0;
let minedLedgerFailed = 0;
let minedCapOverflow = 0;
/**
* The run's mined-mention dedupe set, keyed at (family, key,
* sessionRef) - owned here across turns so one session folds to one
* record per (family, key).
*/
const minedSeen = new Set<string>();
/**
* Hashes a dry run has already forecast. The dedup index only learns a
* hash when a signal actually lands, so without this a marker repeated
* inside one rehearsal would be forecast twice where the real run counts
* one write and one dedup.
*/
const withheldHashes = new Set<string>();
/**
* Dedup hashes of the signals this run actually wrote - the claim the
* post-import census reads back against the vault.
*/
const createdHashes: string[] = [];
const recallTurns: SessionTurn[] = [];
const filterRoles =
opts.filterRoles && opts.filterRoles.length > 0 ? new Set(opts.filterRoles) : null;
const filterNeedle = opts.filterTextIncludes?.trim().toLowerCase() ?? null;
// Inline helper that wraps the writeSignal call with the consistent
// shape every session-imported signal shares.
const emit = (input: {
topic: string;
signal: "positive" | "negative";
principle: string;
scope?: string;
agent: string;
note?: string;
turnId: string;
/** Origin turn's ISO timestamp; used for per-row event-time backfill. */
eventTimestamp?: string;
dedupHash: string;
}): void => {
if (dedup.has(input.dedupHash)) {
signalsDeduped++;
return;
}
if (opts.dryRun) {
// Nothing is written, and the result says so: `signals_created` stays
// 0 and the forecast lands in `signals_withheld` instead.
if (withheldHashes.has(input.dedupHash)) {
signalsDeduped++;
return;
}
withheldHashes.add(input.dedupHash);
signalsWithheld++;
return;
}
const sessionRef = `${sessionKey}#${input.turnId}`;
// Per-row event-time (A2): stamp the turn's original instant when
// preservation is on and the timestamp is usable; otherwise fall
// back to `now` and emit NO bi-temporal slots (byte-identical path).
const { instant, fromTurn } = resolveEventInstant(
input.eventTimestamp,
now,
opts.preserveEventTime === true,
);
try {
const res = writeSignal(vault, {
topic: input.topic,
signal: input.signal,
agent: input.agent,
principle: input.principle,
created_at: isoSecond(instant),
date: isoDate(instant),
slug: input.topic,
...(fromTurn
? {
recorded_at: isoSecond(instant),
valid_from: isoSecond(instant),
// Conversation chronology (S1): carry the turn instant as
// the authoring time so the search layer can expose it and
// break exact hybrid-score ties toward more recent turns.
authored_at: isoSecond(instant),
}
: {}),
...(input.scope ? { scope: input.scope } : {}),
source: [`[[${sessionRef}]]`],
source_type: BRAIN_SIGNAL_SOURCE_TYPE.session,
dedup_hash: input.dedupHash,
session_ref: sessionRef,
...(input.note || opts.ingestScope
? {
raw: [opts.ingestScope ? `[ingest_scope:${opts.ingestScope}]` : "", input.note ?? ""]
.filter((chunk) => chunk.length > 0)
.join("\n"),
}
: {}),
...(opts.rawCodec === true ? { rawCodec: true } : {}),
});
// A session-replayed signal is prompt-derived material by
// definition - it is a turn of an agent conversation - so the
// content-class stamp rides the same run that wrote it (F5). The
// signal writer composes its own frontmatter and exposes no
// extension point, so the stamp lands as a line insert on the
// bytes this call just wrote; a deduped write (empty path) has
// nothing new to stamp. The stamp failing never loses the signal:
// the error surfaces by name in this import's errors, separate
// from the writeSignal arm so neither stage can be mistaken for
// the other.
if (res.path !== "") {
try {
stampPromptDerivedLine(res.path);
} catch (err) {
// The row names `res.path` - the signal page the failure is
// about - never `absPath`, which is the transcript this import
// only read. An operator following the row must land on the
// page that went unstamped.
errors.push({
path: res.path,
message: `content-class stamp failed: ${(err as Error).message ?? String(err)}`,
});
}
}
dedup.set(input.dedupHash, { id: res.id, path: res.path });
createdHashes.push(input.dedupHash);
signalsCreated++;
} catch (err) {
errors.push({
path: absPath,
message: `writeSignal failed: ${(err as Error).message ?? String(err)}`,
});
}
};
// Capture boundary (Memory Integrity Suite): classify the session
// FIRST. An ignored file imports nothing; a stateless file is
// scanned read-only (no signals, no recall records, no facts).
const boundary = buildCaptureBoundary(vault);
const boundaryDecision = boundary.sessionDecision(opts.recallSessionId, absPath);
const mayWrite = boundaryDecision === "capture";
const emptyResult = (): ImportSessionResult =>
Object.freeze({
file: absPath,
format: adapter.id,
write_mode: writeMode,
turns_scanned: 0,
signals_created: 0,
signals_withheld: 0,
signals_deduped: 0,
tool_replays: 0,
skill_invocations: 0,
malformed: 0,
filtered_turns: 0,
boundary_decision: boundaryDecision,
suppressed_turns: 0,
facts_extracted: 0,
facts_withheld: 0,
facts_deduped: 0,
facts_ambient_withheld: 0,
mined_extracted: 0,
mined_deduped: 0,
mined_withheld: 0,
mined_secret_refused: 0,
mined_private_withheld: 0,
mined_ledger_failed: 0,
mined_cap_overflow: 0,
recall_turns_imported: 0,
recall_summary_nodes: 0,
turns_resumed: 0,
resume_discarded: null,
census: censusSessionSignals(vault, []),
errors: Object.freeze([]),
});
if (boundaryDecision === "ignore") return emptyResult();
// Resume (Unit F). Only an APPLIED capture run checkpoints: a dry run
// writes nothing to resume, and a stateless/ignored file is scanned
// read-only. The id folds the import's filters in, so a differently
// filtered run never inherits this one's boundary.
const checkpointActive = opts.dryRun !== true && mayWrite && checkpointingEnabled();
const importId = computeSessionImportId(absPath, opts);
let resumeFrom = 0;
let resumeDiscarded: SessionResumeDiscard | null = null;
let turnsResumed = 0;
let fileIdentity = { headHash: "", bytes: 0 };
if (checkpointActive) {
fileIdentity = {
headHash: computeSessionHeadHash(await readHead()),
bytes: statSync(absPath).size,
};
const decision = resolveSessionResume(vault, importId, fileIdentity);
resumeFrom = decision.turns;
resumeDiscarded = decision.discarded;
}
/**
* Whether a turn belongs to this run's question, and which counter says
* so when it does not. One function because the resumed prefix has to ask
* the same question the main body does - a filter applied on one path and
* not the other would put a turn in the recall DAG that the run's own
* filters exclude.
*/
const admitTurn = (turn: SessionTurn): "admit" | "before_since" | "filtered" | "suppressed" => {
if (sinceMs !== undefined) {
const t = Date.parse(turn.timestamp);
if (Number.isFinite(t) && t < sinceMs) return "before_since";
}
if (filterRoles !== null && !filterRoles.has(turn.role)) return "filtered";
if (filterNeedle !== null) {
const haystack = turn.text?.toLowerCase() ?? "";
if (!haystack.includes(filterNeedle)) return "filtered";
}
// Message-level boundary: suppressed text never reaches marker or
// fact extraction (and is not stored for recall).
if (turn.text && boundary.suppressMessage(turn.text)) return "suppressed";
return "admit";
};
for await (const turn of adapter.iterate(path)) {
turnsScanned++;
// Past the boundary an earlier run recorded: the extraction, the
// hashing and the writes for these turns already happened. The lines
// are still read because a JSONL transcript cannot be seeked into.
if (turnsScanned <= resumeFrom) {
turnsResumed++;
// Recall is the one thing the boundary does NOT vouch for. It is
// accumulated in memory and committed after this loop, so the run
// that stopped at the boundary committed none of it - skipping these
// turns would leave the head of the transcript permanently absent
// from the recall DAG while the run reported success. Re-collecting
// them is cheap (the lines are read either way) and idempotent (the
// recall importer keys each turn on a content dedupe key).
if (opts.recall === true && mayWrite && admitTurn(turn) === "admit") recallTurns.push(turn);
continue;
}
// Everything before THIS turn is done, so the boundary is recorded
// here rather than at the foot of the loop - the body has several
// early `continue`s, and a turn skipped by a filter needs no re-work
// either.
const completedTurns = turnsScanned - 1;
if (
checkpointActive &&
completedTurns > resumeFrom &&
completedTurns % SESSION_CHECKPOINT_TURN_INTERVAL === 0
) {
recordSessionProgress(
vault,
importId,
{
sessionFile: absPath,
headHash: fileIdentity.headHash,
bytes: fileIdentity.bytes,
turnsCompleted: completedTurns,
},
now,
);
}
const admission = admitTurn(turn);
if (admission === "filtered") {
filteredTurns++;
continue;
}
if (admission === "suppressed") {
suppressedTurns++;
continue;
}
if (admission === "before_since") continue;
if (opts.recall === true && mayWrite) recallTurns.push(turn);
// Facts from USER turns only (the HANDOFF carve-out's conservative
// core: bare assistant output is never auto-extracted).
if (mayWrite && turn.text && turn.role === "user") {
const routed = routeExtractedFacts(vault, {
facts: extractFacts(turn.text),
agent: agentLabelForTurn(turn, opts.agent),
now,
sessionRef: `${sessionKey}#${turn.turnId}`,
dedup,
...(opts.dryRun === true ? { dryRun: true } : {}),
});
factsExtracted += routed.created;
factsWithheld += routed.withheld;
factsDeduped += routed.deduped;
factsAmbientWithheld += routed.ambientWithheld;
}
// Mined mentions (recall-quality, B1): provenance-grade, from BOTH
// roles, here in the loop where the raw turn text predates payload
// externalization. A dry run forecasts; a stateless scan never gets
// here (mayWrite is capture-only). Secret-shaped candidates are
// refused and counted inside the miner.
if (mayWrite && turn.text) {
const mined = mineAndRecordTurn(vault, {
vault,
text: turn.text,
sessionRef: sessionKey,
turnId: turn.turnId,
turnTimestamp: turn.timestamp,
now,
seen: minedSeen,
...(opts.dryRun === true ? { dryRun: true } : {}),
});
minedExtracted += mined.extracted;
minedDeduped += mined.deduped;
minedWithheld += mined.withheld;
minedSecretRefused += mined.secretRefused;
minedPrivateWithheld += mined.privateWithheld;
minedLedgerFailed += mined.ledgerFailed;
minedCapOverflow += mined.capOverflow;
}
// Path A — markers in text.
if (mayWrite && turn.text && (turn.role === "user" || turn.role === "assistant")) {
const discovery = discoverMarkersDetailed(turn.text);
malformed += discovery.malformed;
const markers = discovery.markers;
for (const m of markers) {
// Feedback markers only: loop / set markers are never imported
// as signals (loops live-derive, set markers apply via write-back).
if (!isFeedbackMarker(m)) continue;
const hash = computeDedupHash({
topic: m.topic,
signal: m.signal,
principle: m.principle,
...(m.scope ? { scope: m.scope } : {}),
});
emit({
topic: m.topic,
signal: m.signal,
principle: m.principle,
...(m.scope ? { scope: m.scope } : {}),
agent: m.agent ?? agentLabelForTurn(turn, opts.agent),
...(m.note ? { note: m.note } : {}),
turnId: turn.turnId,
eventTimestamp: turn.timestamp,
dedupHash: hash,
});
}
}
// Path B — brain_feedback tool_use replay.
if (!mayWrite) continue;
for (const call of turn.toolCalls ?? []) {
// Per-skill invocation telemetry (t_56a12bde): count real skill
// invocations across runtimes as append-only skill_invoked records.
// Deterministic and idempotent across re-imports (the source ref keys on
// the session + call id + skill, so re-running dedupes rather than
// double-counts). Skipped on a dry run.
const invokedSkill = resolveInvokedSkill(call);
if (invokedSkill !== null && opts.dryRun !== true) {
// Offer provenance (t_ccb05134): when the call cites the offer that
// produced it, the id rides onto the record so the invocation can be
// joined back to that offer. A call citing none is stamped exactly as
// before - the key is omitted, never defaulted, so "no offer was
// cited" can never be read as "offer unknown-but-present".
const citedOffer = readSkillOfferId(call.input);
try {
appendContinuityRecord(vault, {
kind: "skill_invoked",
createdAt: invocationTimestamp(turn.timestamp, now),
sourceRefs: [{ id: `${sessionKey}:${call.id ?? turn.turnId}:${invokedSkill}` }],
payload: {
skill: invokedSkill,
agent: agentLabelForTurn(turn, opts.agent),
tool: call.name,
runtime: adapter.id,
...(citedOffer !== null ? { [SKILL_OFFER_ID_KEY]: citedOffer } : {}),
},
});
skillInvocations++;
} catch {
// Telemetry is best-effort; a failed append never fails the import.
}
}
if (call.name !== "brain_feedback") continue;
const validated = validateBrainFeedbackInput(call.input);
if (!validated.ok) {
malformed++;
continue;
}
const v = validated.value;
const hash = computeDedupHash({
topic: v.topic,
signal: v.signal,
principle: v.principle,
...(v.scope ? { scope: v.scope } : {}),
});
toolReplays++;
emit({
topic: v.topic,
signal: v.signal,
principle: v.principle,
...(v.scope ? { scope: v.scope } : {}),
agent: v.agent ?? agentLabelForTurn(turn, opts.agent),
...(v.raw ? { note: v.raw } : {}),
turnId: call.id ?? turn.turnId,
eventTimestamp: turn.timestamp,
dedupHash: hash,
});
}
}
let recallTurnsImported = 0;
let recallSummaryNodes = 0;
if (opts.recall === true && opts.dryRun !== true && recallTurns.length > 0) {
try {
// Same portable identity used for signal/fact provenance above, so
// the recall DAG and the emitted signals key this session identically.
const recallSessionId = sessionKey;
// Persisted-link resolution only: without a clock the crutch
// never infers a new link, so an unknown session imports flat.
const lineage =
opts.recallLineage ??
resolveSessionLineage({ sessionId: recallSessionId }, { ledger: readLineageLedger(vault) });
const recalled = importSessionRecall(vault, {
sessionId: recallSessionId,
turns: recallTurns,
createdAt: isoSecond(now),
...(opts.recallSummaryGroupSize !== undefined
? { summaryGroupSize: opts.recallSummaryGroupSize }
: {}),
...(lineage.source !== "flat" ? { lineage } : {}),
});
recallTurnsImported = recalled.rawTurns.length;
recallSummaryNodes = recalled.summaryNodes.length;
} catch (err) {
errors.push({
path: absPath,
message: `importSessionRecall failed: ${(err as Error).message ?? String(err)}`,
});
}
}
// Dedup observability (Unit F): one record per import run that actually
// dropped something, keyed by the portable session identity this import
// stamps on every signal it writes. A dry run reports its count and
// writes nothing.
if (opts.dryRun !== true) {
emitIngestDedupReport(vault, {
surface: "session_import",
sources: [{ ref: sessionKey, exactDeduped: signalsDeduped + factsDeduped }],
createdAt: now.toISOString(),
});
}
// The run drained the file, so its resume point has nothing left to say -
// the same settle the ingest lane performs on a fully drained plan, after
// which the dedup index is the authoritative final state.
if (checkpointActive) clearSessionCheckpoint(vault, importId);
return Object.freeze({
file: absPath,
format: adapter.id,
write_mode: writeMode,
turns_scanned: turnsScanned,
signals_created: signalsCreated,
signals_withheld: signalsWithheld,
signals_deduped: signalsDeduped,
tool_replays: toolReplays,
skill_invocations: skillInvocations,
malformed,
boundary_decision: boundaryDecision,
suppressed_turns: suppressedTurns,
facts_extracted: factsExtracted,
facts_withheld: factsWithheld,
facts_deduped: factsDeduped,
facts_ambient_withheld: factsAmbientWithheld,
mined_extracted: minedExtracted,
mined_deduped: minedDeduped,
mined_withheld: minedWithheld,
mined_secret_refused: minedSecretRefused,
mined_private_withheld: minedPrivateWithheld,
mined_ledger_failed: minedLedgerFailed,
mined_cap_overflow: minedCapOverflow,
filtered_turns: filteredTurns,
recall_turns_imported: recallTurnsImported,
recall_summary_nodes: recallSummaryNodes,
turns_resumed: turnsResumed,
resume_discarded: resumeDiscarded,
// Read back AFTER every write this run makes, including the recall
// import above: the point is to ask the disk, not the run's own belief.
census: censusSessionSignals(vault, createdHashes),
errors: Object.freeze(errors),
});
}
/**
* Compose the `agent` field for a session-imported signal. Order of
* preference, highest first:
*
* 1. the marker / tool-input's explicit agent (handled by the caller,
* not here);
* 2. the DELEGATED identity, when the turn carries the host's sub-agent
* id - a sidechain turn was written by a different agent than the one
* that opened the session, and a sub-agent transcript reuses the
* parent's session id, so this is the only place the boundary
* survives;
* 3. `opts.agent` - `--agent` when the operator passed one, otherwise the
* server-resolved identity.
*
* There is no per-adapter constant below that any more. It sat at the TOP
* of this order while being non-empty in every shipped adapter, so
* `opts.agent` was unreachable and `--agent` was validated and discarded;
* and the three constants it stamped - `claude`, `codex`, `hermes` - are
* strings `normalizeAgentArgument` rejects as placeholders on every other
* surface, so imported memory was attributed to a name no writer could
* have named itself.
*/
function agentLabelForTurn(turn: SessionTurn, fallback: string): string {
return turn.agentId !== undefined ? delegatedAgentName(fallback, turn.agentId) : fallback;
}
/**
* Extract the invoked skill name from a tool call, or null when the call is
* not a skill invocation. Counts an actual skill fetch (`get_skill`, however
* namespaced by the runtime) and the host-native `Skill` tool; discovery
* (`list_skills`) and per-turn relevance scoring (`skills_attach`) are not
* invocations and are ignored.
*/
function resolveInvokedSkill(call: SessionToolCall): string | null {
const input = call.input ?? {};
const pick = (key: string): string | null => {
const value = input[key];
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
};
const name = call.name;
if (name === "get_skill" || name.endsWith("__get_skill")) {
return pick("name") ?? pick("skill");
}
if (name === "Skill") {
return pick("command") ?? pick("skill") ?? pick("name");
}
return null;
}
/** ISO-second timestamp for an invocation: the turn's own time when valid. */
function invocationTimestamp(turnTimestamp: string | undefined, now: Date): string {
if (turnTimestamp) {
const ms = Date.parse(turnTimestamp);
if (Number.isFinite(ms) && ms > 0 && ms <= now.getTime()) return isoSecond(new Date(ms));
}
return isoSecond(now);
}
export async function importSessionPath(
vault: string,
path: string,
opts: ImportSessionOptions,
): Promise<ImportSessionPathResult> {
const stat = statSync(path);
if (stat.isFile()) {
const res = await importSession(vault, path, opts);
return Object.freeze({
files: Object.freeze([res]),
warnings: Object.freeze([]),
});
}
// Directory walk: build the dedup index ONCE and thread it through
// every per-file `importSession` call. emit() mutates the shared map
// as new signals are written, so cross-file dedup happens too.
const files: ImportSessionResult[] = [];
const warnings: { path: string; message: string }[] = [];
// Shared with the transcript dataset export, so both agree on what a
// session log is and neither can quietly widen the rule alone.
const queue = sessionFilesUnder(path);
const sharedDedup = opts.dedupIndex ?? (await loadDedupIndex(vault));
const perFileOpts: ImportSessionOptions = {
...opts,
dedupIndex: sharedDedup,
};
// Sequential — writes go to the same Brain/inbox/ and share the
// dedup map; parallelising would race on both.
for (const file of queue) {
try {
const res = await importSession(vault, file, perFileOpts);
files.push(res);
} catch (err) {
if (err instanceof SessionImportError) {
warnings.push({ path: file, message: err.message });
continue;
}
throw err;
}
}
return Object.freeze({
files: Object.freeze(files),
warnings: Object.freeze(warnings),
});
}