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
/**
* Continuity read-model (Memory Observability Suite kernel).
*
* The normalization layer between the raw JSONL continuity store and the
* read-side consumers that go through it. It absorbs three concerns
* exactly once so those consumers cannot disagree on them:
*
* - schema-version dispatch: records written before the stamp
* existed carry no `schema` field and read as v1 (`legacy: true`);
* - masking policy: `private` records are DROPPED by default and
* kept only on explicit request; payload text is already
* redaction-masked at write time and is never un-masked here;
* - fail-soft reads: malformed rows normalize to null and unknown
* kinds stay readable (the evolution rule is additive).
*
* It is NOT the only door onto the store, and the docblock used to imply
* it was. Four modules read through here; twenty call
* `listContinuityRecords` directly and see raw records with none of the
* above applied. `tests/core/brain/continuity/reader-census.test.ts`
* holds both lists and fails when either changes; auditing the direct
* readers is a separate task, by design.
*
* Read-only by construction - this module never writes to the store.
*/
import { listContinuityRecords } from "./store.ts";
import {
CONTINUITY_AGENT_ID_KEY,
CONTINUITY_SCHEMA_VERSION,
CONTINUITY_SESSION_ID_KEY,
CONTINUITY_TURN_ID_KEY,
} from "./types.ts";
export interface NormalizedContinuityRecord {
/** Effective schema version - legacy records report v1. */
readonly schema: string;
/** True when the on-disk record predates the version stamp. */
readonly legacy: boolean;
readonly id: string;
readonly kind: string;
readonly createdAt: string;
readonly sourceRefs: ReadonlyArray<Readonly<Record<string, unknown>>>;
readonly payload: Readonly<Record<string, unknown>>;
readonly private: boolean;
readonly redacted: boolean;
/** Correlation ids lifted out of the payload when present. */
readonly sessionId?: string;
readonly turnId?: string;
/** Authoring agent id lifted out of the payload when present (t_5be0654d). */
readonly agentId?: string;
/** Generation-report handoff lifted to a first-class join field. */
readonly handoffKind?: string;
readonly handoffRef?: string;
}
export interface ContinuityReadModelFilter {
readonly kind?: string;
readonly sessionId?: string;
readonly since?: string;
readonly until?: string;
/** Keep records flagged `private` (default: drop them). */
readonly keepPrivate?: boolean;
}
/** Normalize one raw record (parsed JSONL row). Fail-soft: null on malformed input. */
export function normalizeContinuityRecord(raw: unknown): NormalizedContinuityRecord | null {
if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
const record = raw as Record<string, unknown>;
const id = readString(record["id"]);
const kind = readString(record["kind"]);
const createdAt = readString(record["createdAt"]);
if (id === undefined || kind === undefined || createdAt === undefined) return null;
const schema = readString(record["schema"]);
const payload = isPlainObject(record["payload"])
? (record["payload"] as Record<string, unknown>)
: {};
const sourceRefs = Array.isArray(record["sourceRefs"])
? (record["sourceRefs"] as unknown[]).filter(isPlainObject)
: [];
const sessionId = readString(payload[CONTINUITY_SESSION_ID_KEY]);
const turnId = readString(payload[CONTINUITY_TURN_ID_KEY]);
const agentId = readString(payload[CONTINUITY_AGENT_ID_KEY]);
const handoff = isPlainObject(payload["handoff"]) ? payload["handoff"] : undefined;
const handoffKind = handoff !== undefined ? readString(handoff["kind"]) : undefined;
const handoffRef = handoff !== undefined ? readString(handoff["ref"]) : undefined;
return Object.freeze({
schema: schema ?? CONTINUITY_SCHEMA_VERSION,
legacy: schema === undefined,
id,
kind,
createdAt,
sourceRefs: Object.freeze(sourceRefs.map((ref) => Object.freeze({ ...ref }))),
payload: Object.freeze({ ...payload }),
private: record["private"] === true,
redacted: record["redacted"] === true,
...(sessionId !== undefined ? { sessionId } : {}),
...(turnId !== undefined ? { turnId } : {}),
...(agentId !== undefined ? { agentId } : {}),
...(handoffKind !== undefined ? { handoffKind } : {}),
...(handoffRef !== undefined ? { handoffRef } : {}),
});
}
/** Load, normalize, and filter the whole store. Private records drop unless kept. */
export function loadNormalizedContinuityRecords(
vault: string,
filter: ContinuityReadModelFilter = {},
): ReadonlyArray<NormalizedContinuityRecord> {
const records = listContinuityRecords(vault, {
...(filter.since !== undefined ? { since: filter.since } : {}),
...(filter.until !== undefined ? { until: filter.until } : {}),
});
const normalized: NormalizedContinuityRecord[] = [];
for (const record of records) {
const entry = normalizeContinuityRecord(record);
if (entry === null) continue;
if (entry.private && filter.keepPrivate !== true) continue;
if (filter.kind !== undefined && entry.kind !== filter.kind) continue;
if (filter.sessionId !== undefined && entry.sessionId !== filter.sessionId) continue;
normalized.push(entry);
}
return Object.freeze(normalized);
}
function readString(value: unknown): string | undefined {
return typeof value === "string" && value.length > 0 ? value : undefined;
}
function isPlainObject(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}