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
/**
* Re-hash verification for context receipts (t_4300e5fd).
*
* A context receipt records, per injected item, the sha256 of the text
* the session was DELIVERED. This module answers the operator question
* the receipt left open: is the vault content behind that receipt still
* what the session saw? It re-reads each item's page, re-applies the
* delivery-time transforms, re-hashes with the one digest encoding, and
* reports per item MATCH / CHANGED / NOT AVAILABLE - read-only, no new
* capture machinery, no persistence.
*
* ## What a verdict is a claim about
*
* Delivered bytes, never liveness and never inferred. A retired note
* verifies against its retired body: MATCH says the bytes are the same,
* not that the memory is still live. Only an item carrying BOTH a path
* and a text hash is verifiable; every other item reads as an honest
* `unavailable` with a named reason - a structural id, a hashless item
* and a `pre_compress` principle line (whose recorded text is not
* re-derivable from the vault) are never guessed into a verdict.
*
* ## The projection
*
* The recorded hash covers the delivered text, not the file: for a
* `context_pack` item, the body after frontmatter strip, after the
* context guard, after the `applyCharBudget` cut when the item was
* delivered trimmed; for a `pre_compress` item, the raw file the
* pre-compress writer guarded (no frontmatter strip, no metadata, no
* trust). The receipt records what the re-derivation needs - `trimmed:
* true` and `budget.max_chars_per_memory` - so the kernel re-applies
* exactly that cut; without it, every trimmed item would silently
* false-CHANGED. The projection facts the receipt does not record (the
* cut mode, the delimit guardrail) are re-derived from the vault's
* current config - the same sources the pack builders read at emit time
* - and a changed item whose verdict rode on a config-derived fact names
* that sourcing in its note instead of pretending precision: a config
* change since emit reads as changed, and the note says why.
*
* ## One hash, one resolution rule, never a throw
*
* Re-hashing calls `sha256Hex` from src/core/integrity/digest.ts - the
* exact function the writer used; there is no second hashing path (the
* context-pack-evidence doctrine). Paths resolve against the vault
* defensively: the absolute host paths today's `context_pack` emitter
* records and vault-relative spellings are both accepted, because the
* receipt is data, not a contract about path spelling. A path that
* escapes the vault maps to `unavailable(file_missing)` with a note -
* never a traversal error - and no code path below throws.
*
* `session_inject` receipts carry no text by construction (the
* active-inject hook records id, bytes and tokens only), so every item
* is `unavailable(no_hash)` and the result header says
* `sessionInjected` - the manifest half exists, the re-hash half is out
* of scope by construction, and the result says so instead of pretending.
*/
import { existsSync, readFileSync } from "node:fs";
import { isAbsolute, join, relative } from "node:path";
import { sha256Hex } from "../integrity/digest.ts";
import { DEGRADATION_CODE } from "../integrity/degradation.ts";
import { canonicalNotePath, ensureInsideVault } from "../path-safety.ts";
import { parseFrontmatterWithNotices } from "../vault.ts";
import { isContextReceiptTrigger, type ContextReceiptTrigger } from "./context-receipt-trigger.ts";
import type { ContinuityRecord } from "./continuity/types.ts";
import { loadBrainConfig, loadGuardrailsConfigSafe } from "./policy.ts";
import { dedupReplacementText } from "./context-transforms.ts";
import { applyCharBudget } from "./recall-budget.ts";
import { guardBrainContextSnippet } from "./safety/context-guard.ts";
/** The closed verdict vocabulary of a receipt item verification. */
export const RECEIPT_VERIFY_VERDICT = Object.freeze({
match: "match",
changed: "changed",
unavailable: "unavailable",
} as const);
export type ReceiptVerifyVerdict =
(typeof RECEIPT_VERIFY_VERDICT)[keyof typeof RECEIPT_VERIFY_VERDICT];
/**
* Why an item could not be re-verified at all. `no_hash` covers every
* item whose delivered text left nothing to re-check (no recorded hash,
* a structural id, a session-inject item, a pathless principle line);
* `no_path` is the pathless-but-hashed item outside `pre_compress`;
* `file_missing` and `unreadable` are the two ways a recorded path stops
* answering.
*/
export const RECEIPT_VERIFY_UNAVAILABLE_REASON = Object.freeze({
no_path: "no_path",
no_hash: "no_hash",
file_missing: "file_missing",
unreadable: "unreadable",
} as const);
export type ReceiptVerifyUnavailableReason =
(typeof RECEIPT_VERIFY_UNAVAILABLE_REASON)[keyof typeof RECEIPT_VERIFY_UNAVAILABLE_REASON];
/**
* The membership lists, exported so the verdict-vocabulary census trio is
* complete (values + members + guard) and a refusal can name the
* vocabulary instead of restating it - the same rule
* `DELIVERY_TREATMENTS` follows.
*/
export const RECEIPT_VERIFY_VERDICTS: ReadonlyArray<ReceiptVerifyVerdict> = Object.freeze(
Object.values(RECEIPT_VERIFY_VERDICT) as ReceiptVerifyVerdict[],
);
export const RECEIPT_VERIFY_UNAVAILABLE_REASONS: ReadonlyArray<ReceiptVerifyUnavailableReason> =
Object.freeze(
Object.values(RECEIPT_VERIFY_UNAVAILABLE_REASON) as ReceiptVerifyUnavailableReason[],
);
/** Takes `unknown`: a verdict can arrive from a persisted or wire payload. */
export function isReceiptVerifyVerdict(value: unknown): value is ReceiptVerifyVerdict {
return (
typeof value === "string" && (RECEIPT_VERIFY_VERDICTS as ReadonlyArray<string>).includes(value)
);
}
/** Takes `unknown`: an unavailable reason can arrive from a wire payload. */
export function isReceiptVerifyUnavailableReason(
value: unknown,
): value is ReceiptVerifyUnavailableReason {
return (
typeof value === "string" &&
(RECEIPT_VERIFY_UNAVAILABLE_REASONS as ReadonlyArray<string>).includes(value)
);
}
/**
* The header marker for a receipt whose trigger is not a member of the
* closed `ContextReceiptTrigger` vocabulary. The header never asserts a
* trigger the receipt did not carry: `trigger` names the gap and
* `triggerRaw` carries the receipt's own string value beside it, instead
* of the old fallback literal claiming `context_pack`.
*/
export const RECEIPT_TRIGGER_UNKNOWN = "unknown";
/** One receipt item's verification outcome. */
export interface ReceiptItemVerification {
readonly id: string;
/** The path as the receipt recorded it, when it recorded one. */
readonly path: string | null;
readonly verdict: ReceiptVerifyVerdict;
/** The digest the receipt recorded, when it recorded one. */
readonly expectedHash: string | null;
/** The re-computed digest; null whenever the item is unavailable. */
readonly observedHash: string | null;
readonly unavailableReason: ReceiptVerifyUnavailableReason | null;
/**
* Why an item is unavailable, or why a verdict could not be derived
* the plain way. Always null on `match` and on a plain `changed`.
*/
readonly note: string | null;
}
/** The verification of one whole receipt. */
export interface ReceiptVerification {
readonly receiptId: string;
readonly createdAt: string;
/**
* The closed-vocabulary trigger the projection ran under, or the
* unknown marker when the receipt's own trigger is not a member - the
* header never asserts a trigger the receipt did not carry.
*/
readonly trigger: ContextReceiptTrigger | typeof RECEIPT_TRIGGER_UNKNOWN;
/**
* The receipt's own trigger value when it was not a vocabulary member
* (string raws only; a non-string raw has no honest value to carry and
* reads as null beside the marker).
*/
readonly triggerRaw: string | null;
readonly sessionInjected: boolean;
readonly items: ReadonlyArray<ReceiptItemVerification>;
readonly counts: { match: number; changed: number; unavailable: number };
}
/** The item fields the verification reads, read defensively off the payload. */
interface ReceiptItemData {
readonly id: string;
readonly path: string | null;
readonly expectedHash: string | null;
readonly trimmed: boolean;
/** The first copy's id when the writer replaced this item's body (additive). */
readonly dedupedFrom: string | null;
}
/**
* Verify one context receipt against the vault it was drawn from.
*
* `receipt` is the stored `context_receipt` continuity record (as
* `getContextReceipt` returns it). The walk is read-only and never
* throws: every per-item failure mode lands in the closed
* `unavailable` class with a note, so a hostile or stale receipt
* degrades to an honest report instead of an error.
*/
export function verifyContextReceipt(
vault: string,
receipt: ContinuityRecord,
): ReceiptVerification {
const payload = receipt.payload;
const rawTrigger = payload["trigger"];
const triggerKnown = isContextReceiptTrigger(rawTrigger);
const trigger: ContextReceiptTrigger | typeof RECEIPT_TRIGGER_UNKNOWN = triggerKnown
? rawTrigger
: RECEIPT_TRIGGER_UNKNOWN;
// An unreadable trigger means the delivery-time projection cannot be
// chosen, so nothing on the receipt is verifiable; the per-item notes
// carry that, and the counts stay honest. The header answers with the
// unknown marker and the raw value, never a vocabulary member the
// receipt did not carry.
const triggerUnreadable = !triggerKnown;
const sessionInjected = triggerKnown && rawTrigger === "session_inject";
const maxCharsPerMemory = budgetMaxCharsPerMemory(payload["budget"]);
// The delivery-time projection facts the receipt does not record are
// re-derived from the vault's current config - the same sources the
// pack builders read at emit time - and a changed item names that
// sourcing instead of pretending precision (see verifyItem).
const degradation = resolveDegradation(vault, payload["budget"]);
const delimitUntrusted = resolveDelimitUntrusted(vault);
const items = readReceiptItems(payload).map((item) =>
verifyItem(vault, item, {
trigger,
triggerUnreadable,
sessionInjected,
maxCharsPerMemory,
degradation: degradation.mode,
degradationFromConfig: degradation.fromConfig,
delimitUntrusted,
}),
);
const counts = { match: 0, changed: 0, unavailable: 0 };
for (const item of items) counts[item.verdict] += 1;
return Object.freeze({
receiptId: receipt.id,
createdAt: receipt.createdAt,
trigger,
triggerRaw:
!triggerKnown && typeof rawTrigger === "string" && rawTrigger.length > 0 ? rawTrigger : null,
sessionInjected,
items: Object.freeze(items),
counts: Object.freeze(counts),
});
}
/** Read the receipt's item list; entries without a readable id are skipped, as the fold skips them. */
function readReceiptItems(
payload: Readonly<Record<string, unknown>>,
): ReadonlyArray<ReceiptItemData> {
const stored = payload["items"];
if (!Array.isArray(stored)) return [];
const items: ReceiptItemData[] = [];
for (const raw of stored) {
if (raw === null || typeof raw !== "object") continue;
const item = raw as Record<string, unknown>;
const id = item["id"];
if (typeof id !== "string" || id.length === 0) continue;
const path = item["path"];
const hash = item["text_hash"];
const dedupedFrom = item["deduped_from"];
items.push({
id,
path: typeof path === "string" && path.length > 0 ? path : null,
expectedHash: typeof hash === "string" && hash.length > 0 ? hash : null,
trimmed: item["trimmed"] === true,
dedupedFrom: typeof dedupedFrom === "string" && dedupedFrom.length > 0 ? dedupedFrom : null,
});
}
return items;
}
/** Everything {@link verifyItem} needs beside the item itself. */
interface VerifyEnvironment {
readonly trigger: ContextReceiptTrigger | typeof RECEIPT_TRIGGER_UNKNOWN;
readonly triggerUnreadable: boolean;
readonly sessionInjected: boolean;
readonly maxCharsPerMemory: number | null;
/** The cut mode the re-applied budget uses; undefined is the default hard cut. */
readonly degradation: "staged" | undefined;
/** True when the cut mode had to be re-derived from the vault's current config. */
readonly degradationFromConfig: boolean;
/** The writer's delimit guardrail, re-derived from the vault's current config. */
readonly delimitUntrusted: boolean;
}
function verifyItem(
vault: string,
item: ReceiptItemData,
env: VerifyEnvironment,
): ReceiptItemVerification {
if (env.sessionInjected) {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.no_hash,
"session_inject receipts record id, bytes and tokens only, so there is no " +
"delivered text to re-hash - not verifiable by construction",
);
}
if (env.triggerUnreadable) {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.no_hash,
"the receipt's trigger is not a context-receipt trigger, so the " +
"delivery-time projection cannot be chosen",
);
}
if (item.expectedHash === null) {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.no_hash,
"the item records no text hash, so there is nothing to re-check",
);
}
if (item.dedupedFrom !== null && env.trigger === "context_pack") {
// The dedup transform replaced this item's delivered body with the
// shared omission sentence naming the first copy: the delivered
// bytes are synthetic, deterministic from the recorded id, and NOT
// a projection of the page - so the re-derivation is the sentence
// itself, and the page behind the FIRST copy is what that item's
// own verification covers.
const observedHash = sha256Hex(dedupReplacementText(item.dedupedFrom));
return Object.freeze({
id: item.id,
path: item.path,
verdict:
observedHash === item.expectedHash
? RECEIPT_VERIFY_VERDICT.match
: RECEIPT_VERIFY_VERDICT.changed,
expectedHash: item.expectedHash,
observedHash,
unavailableReason: null,
note: null,
});
}
if (item.path === null) {
if (env.trigger === "pre_compress") {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.no_hash,
"the recorded text is a principle line, not vault content - no " +
"projection re-derives it from the vault",
);
}
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.no_path,
"the item records no path to re-read",
);
}
// The receipt is data, not a contract about path spelling: accept the
// absolute host paths today's emitter records and vault-relative
// spellings alike, and map an escape to an honest unavailable.
let absolute: string;
try {
absolute = ensureInsideVault(isAbsolute(item.path) ? item.path : join(vault, item.path), vault);
} catch {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.file_missing,
"the recorded path does not resolve inside the vault, so it is not read",
);
}
if (!existsSync(absolute)) {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.file_missing,
"the recorded path no longer exists in the vault",
);
}
let raw: string;
let meta: Readonly<Record<string, unknown>>;
let body: string;
try {
raw = readFileSync(absolute, "utf8");
const parsed = parseFrontmatterWithNotices(absolute);
meta = parsed[0];
body = parsed[1];
if (parsed[2].some((notice) => notice.code === DEGRADATION_CODE.frontmatterUnreadable)) {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.unreadable,
"the page could not be read",
);
}
} catch {
return unavailable(
item,
RECEIPT_VERIFY_UNAVAILABLE_REASON.unreadable,
"the page could not be read",
);
}
const projected =
env.trigger === "pre_compress"
? projectPreCompressText(item, absolute, raw.trim(), env)
: projectContextPackText(vault, item, absolute, body, meta, env);
const observedHash = sha256Hex(projected);
const changed = observedHash !== item.expectedHash;
return Object.freeze({
id: item.id,
path: item.path,
verdict: changed ? RECEIPT_VERIFY_VERDICT.changed : RECEIPT_VERIFY_VERDICT.match,
expectedHash: item.expectedHash,
observedHash,
unavailableReason: null,
// A verdict that could not be derived the plain way says exactly what
// stood in the way instead of pretending precision: a trimmed item
// whose receipt lost its budget block, and the projection facts that
// had to be re-derived from the vault's current config because the
// receipt records none.
note: changedProjectionNote(item, env),
});
}
/**
* The note a changed verdict carries when the projection could not be
* derived from recorded data alone. Null on a plain changed: an edit is
* an edit, and a note on every one would bury the projection gaps.
*/
function changedProjectionNote(item: ReceiptItemData, env: VerifyEnvironment): string | null {
const gaps: string[] = [];
if (item.trimmed && env.maxCharsPerMemory === null) {
gaps.push(
"the item is marked trimmed but the receipt records no " +
"max_chars_per_memory, so the recorded cut cannot be re-applied",
);
} else if (item.trimmed && env.degradationFromConfig) {
gaps.push(
"the receipt's budget block records no cut mode, so the staged cut " +
"was re-derived from the vault's current config",
);
}
if (env.delimitUntrusted && env.trigger !== "pre_compress") {
gaps.push(
"the untrusted-source delimiting guardrail was re-derived from the " +
"vault's current config",
);
}
if (gaps.length === 0) return null;
return `${gaps.join("; ")} - a delivery-config change since emit reads as changed`;
}
/**
* Re-derive the delivered text of a `context_pack` item: the body after
* frontmatter strip, after the context guard with the page's current
* frontmatter as the guard source (metadata and trust), path included,
* and the delimit guardrail the vault's current config names - the same
* guard call the context-pack builders make - then the recorded budget
* cut when the item was delivered trimmed.
*/
function projectContextPackText(
vault: string,
item: ReceiptItemData,
absolute: string,
body: string,
meta: Readonly<Record<string, unknown>>,
env: VerifyEnvironment,
): string {
const guarded = guardBrainContextSnippet(body, {
source: { id: item.id, path: absolute, metadata: meta },
...(meta["context_safety"] === "trusted-instruction"
? { trust: "trusted-instruction" as const }
: {}),
...(env.delimitUntrusted
? {
delimitUntrusted: true,
provenancePath: canonicalNotePath(relative(vault, absolute)),
}
: {}),
});
return cutToBudget(item, guarded.safeText, env);
}
/**
* Re-derive the delivered text of a `pre_compress` item: the pre-compress
* writer guards the WHOLE file - the raw file bytes, no frontmatter
* strip - with source `{id, path}` and no metadata or trust, and never
* passes the delimit guardrail. The projection reproduces exactly that,
* so a frontmatter value that moved the writer's bytes moves the verdict
* the same way instead of reading as a phantom change.
*/
function projectPreCompressText(
item: ReceiptItemData,
absolute: string,
rawFile: string,
env: VerifyEnvironment,
): string {
const guarded = guardBrainContextSnippet(rawFile, {
source: { id: item.id, path: absolute },
});
return cutToBudget(item, guarded.safeText, env);
}
/** The recorded budget cut, in the cut mode the writer used. */
function cutToBudget(item: ReceiptItemData, text: string, env: VerifyEnvironment): string {
if (item.trimmed && env.maxCharsPerMemory !== null) {
return applyCharBudget([{ item: item.id, text }], {
maxCharsPerEntry: env.maxCharsPerMemory,
...(env.degradation !== undefined ? { degradation: env.degradation } : {}),
}).kept[0]!.text;
}
return text;
}
/**
* The cut mode the re-applied budget uses. A receipt whose budget block
* records the mode (additive, forward-compatible) is honored verbatim;
* otherwise the vault's current `recall.degradation` config is the only
* source - the same source the pack builders read at emit time - and the
* sourcing is reported so a changed trimmed item can name the gap.
*/
function resolveDegradation(
vault: string,
budget: unknown,
): { mode: "staged" | undefined; fromConfig: boolean } {
if (typeof budget === "object" && budget !== null) {
const recorded = (budget as Record<string, unknown>)["degradation"];
if (recorded === "staged") return { mode: "staged", fromConfig: false };
}
try {
return {
mode: loadBrainConfig(vault).recall?.degradation === "staged" ? "staged" : undefined,
fromConfig: true,
};
} catch {
return { mode: undefined, fromConfig: true };
}
}
/** The writer's delimit guardrail, read the way the pack builders read it. */
function resolveDelimitUntrusted(vault: string): boolean {
try {
return loadGuardrailsConfigSafe(vault).untrusted_source_delimiting === true;
} catch {
return false;
}
}
/** The recorded per-memory char budget, when the receipt carries a usable one. */
function budgetMaxCharsPerMemory(raw: unknown): number | null {
if (typeof raw !== "object" || raw === null) return null;
const value = (raw as Record<string, unknown>)["max_chars_per_memory"];
if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return null;
return Math.floor(value);
}
/** The one unavailable outcome, with the reason and note that name it. */
function unavailable(
item: ReceiptItemData,
reason: ReceiptVerifyUnavailableReason,
note: string,
): ReceiptItemVerification {
return Object.freeze({
id: item.id,
path: item.path,
verdict: RECEIPT_VERIFY_VERDICT.unavailable,
expectedHash: item.expectedHash,
observedHash: null,
unavailableReason: reason,
note,
});
}