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
/**
* Decision-change receipts (Belief lifecycle suite, B4, t_3547314d).
*
* A `decision_change.v1` receipt is an append-only accountability record
* emitted at the moment a belief changes: what it was (`before`), what it
* became (`after`), the evidence that triggered the change, the
* confidence delta, the alternatives considered, the actor, a rationale,
* and a machine reason code. Receipts are append-only accountability, NOT
* rollback (typed revertible history is a separate ADR wave, out of scope
* here).
*
* Storage mirrors the truth ledger's shard discipline (`truth/store.ts`):
* device-sharded append-only JSONL alongside the truth ledger shards
* (`Brain/truth/decision-change[.<deviceId>].jsonl`), Syncthing-safe and
* fail-closed per line. The claim reader ignores these shards (its regex
* only matches `claims*.jsonl`), and this reader ignores claim shards.
*
* Durability + idempotency: the key is a sha256 of `subject + before +
* after`, so replaying the same change is a no-op - the second append
* finds the key already present and returns the existing receipt. The
* schema is CLOSED: any field outside the accountable set (e.g. a hidden
* free-text reasoning field) is rejected with a typed error. History is
* queryable with an opaque cursor and exact counts. Reads never write.
*/
import { mkdirSync, appendFileSync, readdirSync, readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { join } from "node:path";
import { resolveDeviceId } from "../../config.ts";
import {
JSONL_LEDGER_EXT,
jsonlLedgerGrammar,
parseShardedName,
shardedFileName,
} from "../ledger-shards.ts";
import { appendLogEvent } from "../log.ts";
import { decodeOffsetCursor, encodeOffsetCursor } from "../offset-cursor.ts";
import { BRAIN_LOG_EVENT_KIND } from "../types.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { readLedgerRows } from "../../store/read/ledger-rows.ts";
import { isStoreOnly } from "../../store/store-only.ts";
import { routeWrite } from "../../store/store-write.ts";
import { DUAL_WRITE_LEDGERS, ledgerRowRecord } from "../../store/dual-write-records.ts";
import { rowNamesPrivatePage } from "../../store/reference-privacy.ts";
/** Schema tag stamped on every receipt line. */
export const DECISION_CHANGE_SCHEMA_VERSION = "decision_change.v1";
/**
* Sentinel `before`/`after` state for a receipt whose belief did not
* exist on that side of the change (a creation has no prior state). The
* closed schema requires a non-empty string, so an absent state is this
* explicit marker rather than the empty string.
*/
export const RECEIPT_ABSENT_STATE = "(absent)";
/**
* Closed reason-code vocabulary for decision-record change receipts. A
* decision mutation stamps exactly one of these so the change trail is
* machine-filterable alongside the lifecycle codes (supersede/tombstone).
* `openResolved` (write-side-trust wave, Task 10) stamps the transition
* that closed an open decision by minting a real decision page: the
* receipt's subject is the OPEN record, so the trail answers "which
* parked question became this decision".
*/
export const DECISION_CHANGE_REASON = Object.freeze({
record: "decision-record",
outcome: "decision-outcome",
rating: "decision-rating",
openResolved: "open-resolved",
} as const);
/** Same canonical UTC shape the truth ledger and log writer emit. */
const ISO_UTC_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
/** `decision-change.jsonl` or `decision-change.<deviceId>.jsonl`, via the shared ledger-shard grammar. */
const RECEIPT_STEM = "decision-change";
export const RECEIPT_GRAMMAR = jsonlLedgerGrammar(RECEIPT_STEM);
/** Cap on the length of any single string field (mirrors note-text caps). */
const FIELD_MAX_LEN = 2000;
/** Default page size for {@link queryDecisionChangeHistory}. */
export const DECISION_HISTORY_DEFAULT_LIMIT = 50;
/**
* The one `errno` that means the receipt store was never created, as
* opposed to created and unreachable. See
* {@link readDecisionChangeReceipts}.
*/
const DIR_ABSENT_ERRNO = "ENOENT";
/** Every failure path in this module raises this typed error. */
export class ReceiptError extends Error {
constructor(message: string, options?: ErrorOptions) {
super(message, options);
this.name = "ReceiptError";
}
}
// ----- Shapes ---------------------------------------------------------------
export interface DecisionChangeReceipt {
readonly v: typeof DECISION_CHANGE_SCHEMA_VERSION;
readonly ts: string;
/** Id/wikilink of the belief that changed. */
readonly subject: string;
/** Canonical before-state string. */
readonly before: string;
/** Canonical after-state string. */
readonly after: string;
/** Wikilinks/ids of the evidence that triggered the change. */
readonly evidence_triggers: ReadonlyArray<string>;
/** Confidence movement (after - before), or `null` when not applicable. */
readonly confidence_delta: number | null;
/** Alternatives considered but not chosen. */
readonly alternatives: ReadonlyArray<string>;
/** Agent/human who made the change. */
readonly actor: string;
/** Accountable justification (a permitted free-text field). */
readonly rationale: string;
/** Machine reason code (e.g. `supersede`, `tombstone`, `confidence-refresh`). */
readonly reason_code: string;
/** sha256(subject + before + after); replays are no-ops. */
readonly idempotency_key: string;
}
export interface AppendReceiptInput {
readonly subject: string;
readonly before: string;
readonly after: string;
readonly evidenceTriggers?: ReadonlyArray<string>;
readonly confidenceDelta?: number | null;
readonly alternatives?: ReadonlyArray<string>;
readonly actor: string;
readonly rationale?: string;
readonly reasonCode: string;
/** ISO-8601 UTC instant; defaults to now. */
readonly ts?: string;
readonly configPath?: string;
}
export interface AppendReceiptResult {
readonly appended: boolean;
readonly path: string;
readonly receipt: DecisionChangeReceipt;
}
/**
* The closed set of accepted input keys. Any key outside this set is a
* schema violation - this is what rejects a hidden free-text reasoning
* field smuggled onto the input.
*/
const ALLOWED_INPUT_KEYS: ReadonlySet<string> = new Set([
"subject",
"before",
"after",
"evidenceTriggers",
"confidenceDelta",
"alternatives",
"actor",
"rationale",
"reasonCode",
"ts",
"configPath",
]);
// ----- Paths ----------------------------------------------------------------
/** Receipt shards live alongside the truth ledger shards. */
export function receiptsDir(vault: string): string {
return join(vault, "Brain", "truth");
}
/**
* The receipt shard this device appends to.
*
* @throws {@link ConfigReadError} when the device-local config naming this
* device cannot be read. Propagated rather than falling back to the
* legacy un-sharded `decision-change.jsonl`: `resolveDeviceId` would
* otherwise mint and persist a fresh id over a config it could not read
* (see its docblock), and a silent shard switch would scatter one
* device's receipts across two files with nothing recording why. The
* error names the file and the way out; the CLI verb wrapping this call
* prints it, and `O2B_DEVICE_ID` resolves the append without the file.
*/
export function receiptShardPath(vault: string, configPath?: string): string {
const deviceId = resolveDeviceId(configPath);
const name = shardedFileName(RECEIPT_STEM, deviceId, JSONL_LEDGER_EXT);
return join(receiptsDir(vault), name);
}
// ----- Validation -----------------------------------------------------------
function requireString(value: unknown, label: string): string {
if (typeof value !== "string" || value.trim() === "") {
throw new ReceiptError(`receipt: ${label} is required`);
}
if (value.length > FIELD_MAX_LEN) {
throw new ReceiptError(`receipt: ${label} exceeds ${FIELD_MAX_LEN} chars`);
}
return value.trim();
}
function optionalStringList(value: unknown, label: string): ReadonlyArray<string> {
if (value === undefined || value === null) return [];
if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
throw new ReceiptError(`receipt: ${label} must be a list of strings`);
}
return value.map((v) => (v as string).trim()).filter((v) => v.length > 0);
}
function computeIdempotencyKey(subject: string, before: string, after: string): string {
return createHash("sha256").update(`${subject}\n${before}\n${after}`, "utf8").digest("hex");
}
/**
* Reduce a receipt subject to its bare identifier for read-side matching.
*
* Receipts store `subject` in whichever shape the writer had on hand: a
* decision record's B4 hook stamps a wikilink (`[[decision-adopt-bun]]`,
* `record.ts`), while the lifecycle tombstone/supersede hook stamps a bare
* vault-relative path (`Brain/decisions/decision-adopt-bun.md`,
* `lifecycle/tombstone.ts`). A history query filtering by subject would
* otherwise require the caller to know which writer produced a given
* receipt. This strips, in order: a `[[ ]]` wikilink fence (and any
* `|alias` display suffix), a leading directory prefix, and a trailing
* `.md` extension - so the bare id, wikilink, and full-path forms of the
* same subject all normalize to one value. Storage is untouched; this is
* read-side normalization only, applied at query time in
* {@link queryDecisionChangeHistory}.
*/
export function normalizeDecisionSubject(raw: string): string {
let value = raw.trim();
const fence = /^\[\[([^\]]+)\]\]$/.exec(value);
if (fence) value = fence[1]!.trim();
const pipe = value.indexOf("|");
if (pipe >= 0) value = value.slice(0, pipe).trim();
const slash = Math.max(value.lastIndexOf("/"), value.lastIndexOf("\\"));
if (slash >= 0) value = value.slice(slash + 1);
if (value.toLowerCase().endsWith(".md")) value = value.slice(0, -3);
return value;
}
// ----- Append ---------------------------------------------------------------
/**
* Validate and append one decision-change receipt. Idempotent: if a
* receipt with the same `subject + before + after` key already exists,
* this is a no-op returning the existing receipt with `appended: false`.
*/
export function appendDecisionChangeReceipt(
vault: string,
input: AppendReceiptInput,
): AppendReceiptResult {
// Closed-schema gate: reject any unexpected field before doing anything.
for (const key of Object.keys(input)) {
if (!ALLOWED_INPUT_KEYS.has(key)) {
throw new ReceiptError(`receipt: unexpected field ${JSON.stringify(key)} is not permitted`);
}
}
const subject = requireString(input.subject, "subject");
const before = requireString(input.before, "before");
const after = requireString(input.after, "after");
const actor = requireString(input.actor, "actor");
const reasonCode = requireString(input.reasonCode, "reasonCode");
const rationale =
input.rationale === undefined || input.rationale === null
? ""
: requireString(input.rationale, "rationale");
const evidenceTriggers = optionalStringList(input.evidenceTriggers, "evidenceTriggers");
const alternatives = optionalStringList(input.alternatives, "alternatives");
let confidenceDelta: number | null = null;
if (input.confidenceDelta !== undefined && input.confidenceDelta !== null) {
if (typeof input.confidenceDelta !== "number" || !Number.isFinite(input.confidenceDelta)) {
throw new ReceiptError("receipt: confidenceDelta must be a finite number or null");
}
confidenceDelta = input.confidenceDelta;
}
const ts = input.ts ?? new Date().toISOString();
if (!ISO_UTC_TS_RE.test(ts)) {
throw new ReceiptError(`receipt: ts must be canonical ISO-8601 UTC: ${JSON.stringify(ts)}`);
}
const idempotencyKey = computeIdempotencyKey(subject, before, after);
// Idempotency: a matching key already on disk makes this a no-op. The
// read raises rather than reporting an empty store when the directory
// exists and cannot be listed, so a replay under a denied read refuses
// instead of appending a second copy of the same change.
const readOptions = input.configPath !== undefined ? { configPath: input.configPath } : {};
const storeOnly = isStoreOnly({ vault, ...readOptions });
const existing = readDecisionChangeReceipts(vault, readOptions).receipts.find(
(r) => r.idempotency_key === idempotencyKey,
);
if (existing) {
// The same `path` rule as an append: the shard on an unswitched
// machine, the store ledger once switched (no legacy path that never
// exists there).
return Object.freeze({
appended: false,
path: storeOnly ? RECEIPT_STORE_SOURCE : receiptShardPath(vault, input.configPath),
receipt: existing,
});
}
const receipt: DecisionChangeReceipt = Object.freeze({
v: DECISION_CHANGE_SCHEMA_VERSION,
ts,
subject,
before,
after,
evidence_triggers: Object.freeze([...evidenceTriggers]),
confidence_delta: confidenceDelta,
alternatives: Object.freeze([...alternatives]),
actor,
rationale,
reason_code: reasonCode,
idempotency_key: idempotencyKey,
});
// One `decision-receipts` ledger row on a store-only machine (design D14
// item 1), this device's receipt shard plus the dual write otherwise. A
// receipt about a private item (its subject, evidence or rationale names
// a private or unjudgeable preference or page) stays out of `shared`.
const routed = routeWrite({
legacy: () => {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
mkdirSync(receiptsDir(vault), { recursive: true });
const shard = receiptShardPath(vault, input.configPath);
appendFileSync(shard, JSON.stringify(receipt) + "\n");
return shard;
},
store: () =>
ledgerRowRecord(
DUAL_WRITE_LEDGERS.decisionReceipts,
receipt,
rowNamesPrivatePage(vault, receipt) ? "private" : "shared",
),
context: { vault, ...(input.configPath !== undefined ? { configPath: input.configPath } : {}) },
});
// The store ledger names the receipt once switched, for an append and a
// replay alike (never a device-local shard path).
const path = routed.mode === "legacy" ? routed.value : RECEIPT_STORE_SOURCE;
// Surface the change in the merged activity timeline. Emitted only on an
// actual append, never on an idempotent replay, so the log never
// double-counts a change. Fail-soft: a log hiccup must not lose the receipt.
try {
appendLogEvent(
vault,
{
timestamp: ts,
eventType: BRAIN_LOG_EVENT_KIND.decisionChangeReceipt,
body: {
subject,
reason_code: reasonCode,
idempotency_key: idempotencyKey,
agent: actor,
},
},
{ failOpen: true },
);
} catch {
// The JSONL receipt is authoritative; the timeline mirror is best-effort.
}
return Object.freeze({ appended: true, path, receipt });
}
// ----- Read -----------------------------------------------------------------
export interface ReceiptParseWarning {
readonly path: string;
readonly lineNumber: number;
readonly message: string;
}
export interface ReadReceiptsResult {
readonly receipts: ReadonlyArray<DecisionChangeReceipt>;
readonly warnings: ReadonlyArray<ReceiptParseWarning>;
}
/**
* Read every receipt merged across device shards, sorted by
* (ts, shardId, line). Fail-closed per line: a malformed or
* unknown-version line surfaces as a warning. Never writes.
*
* ## An unreadable directory is not an empty one
*
* The directory read used to be wrapped in a bare `catch` returning no
* receipts and no warnings, which gave a vault whose `Brain/truth/` the
* process cannot enter exactly the answer a vault that has never
* recorded a decision gets. Two consequences, both real:
*
* - every read surface - the history query, the audit join - reported
* "no decisions" for a store it had not looked at;
* - the idempotency probe in {@link appendDecisionChangeReceipt} reads
* through this function, so an unreadable directory read as "no
* prior receipt with this key" and the append went ahead. The one
* guard against a duplicated accountability record was disabled by
* precisely the condition under which it mattered most.
*
* So only ABSENCE is quiet, and it is quiet because a vault that has
* never appended a receipt legitimately has no directory. Every other
* failure - a permission denial, a file standing where the directory
* should be, an I/O error - raises {@link ReceiptError} naming the path.
* Per-shard failures below stay warnings: there the reader knows what it
* did and did not read, and can say so.
*
* @throws {@link ReceiptError} when the receipt directory exists and
* cannot be listed.
*/
export function readDecisionChangeReceipts(
vault: string,
options: { readonly configPath?: string } = {},
): ReadReceiptsResult {
// A store-only machine (design D14 item 1) reads the `decision-receipts`
// ledger rows, sorted by `ts` with fold order breaking ties. The machine
// config decides the mode and the store, as it does for the append.
const context = {
vault,
...(options.configPath !== undefined ? { configPath: options.configPath } : {}),
};
if (isStoreOnly(context)) {
const warnings: ReceiptParseWarning[] = [];
const receipts: DecisionChangeReceipt[] = [];
readLedgerRows<unknown>(DUAL_WRITE_LEDGERS.decisionReceipts, () => [], context).forEach(
(row, index) => {
const receipt = coerceReceipt(row, RECEIPT_STORE_SOURCE, index + 1, warnings);
if (receipt !== null) receipts.push(receipt);
},
);
return {
receipts: receipts.toSorted((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0)),
warnings,
};
}
const dir = receiptsDir(vault);
let names: string[];
try {
names = readdirSync(dir).toSorted();
} catch (err) {
if ((err as NodeJS.ErrnoException).code === DIR_ABSENT_ERRNO) {
return { receipts: [], warnings: [] };
}
throw new ReceiptError(
`receipt: failed to list ${dir}: ${(err as Error).message ?? String(err)}`,
{ cause: err },
);
}
interface Tagged {
readonly receipt: DecisionChangeReceipt;
readonly shardId: string;
readonly line: number;
}
const tagged: Tagged[] = [];
const warnings: ReceiptParseWarning[] = [];
for (const name of names) {
const shard = parseShardedName(name, RECEIPT_GRAMMAR);
if (shard === null) continue;
const shardId = shard.shardId;
const path = join(dir, name);
let text: string;
try {
text = readFileSync(path, "utf8");
} catch (err) {
warnings.push({
path,
lineNumber: 0,
message: `failed to read shard: ${(err as NodeJS.ErrnoException).message ?? String(err)}`,
});
continue;
}
const lines = text.split(/\r?\n/);
for (let i = 0; i < lines.length; i++) {
const line = lines[i]!;
if (line.trim() === "") continue;
let parsed: unknown;
try {
parsed = JSON.parse(line);
} catch {
warnings.push({ path, lineNumber: i + 1, message: `malformed JSONL line` });
continue;
}
const receipt = coerceReceipt(parsed, path, i + 1, warnings);
if (receipt !== null) tagged.push({ receipt, shardId, line: i });
}
}
tagged.sort((a, b) => {
if (a.receipt.ts !== b.receipt.ts) return a.receipt.ts < b.receipt.ts ? -1 : 1;
if (a.shardId !== b.shardId) return a.shardId < b.shardId ? -1 : 1;
return a.line - b.line;
});
return { receipts: tagged.map((t) => t.receipt), warnings };
}
/** The `path` a warning about a store row names: the ledger it came from. */
const RECEIPT_STORE_SOURCE = `store:ledgers/${DUAL_WRITE_LEDGERS.decisionReceipts}`;
function coerceReceipt(
parsed: unknown,
path: string,
lineNumber: number,
warnings: ReceiptParseWarning[],
): DecisionChangeReceipt | null {
if (typeof parsed !== "object" || parsed === null) {
warnings.push({ path, lineNumber, message: "not an object" });
return null;
}
const r = parsed as Record<string, unknown>;
if (r["v"] !== DECISION_CHANGE_SCHEMA_VERSION) {
warnings.push({ path, lineNumber, message: `unknown schema version ${String(r["v"])}` });
return null;
}
if (
typeof r["subject"] !== "string" ||
typeof r["before"] !== "string" ||
typeof r["after"] !== "string" ||
typeof r["idempotency_key"] !== "string"
) {
warnings.push({ path, lineNumber, message: "missing required field" });
return null;
}
return Object.freeze({
v: DECISION_CHANGE_SCHEMA_VERSION,
ts: typeof r["ts"] === "string" ? r["ts"] : "",
subject: r["subject"] as string,
before: r["before"] as string,
after: r["after"] as string,
evidence_triggers: Array.isArray(r["evidence_triggers"])
? (r["evidence_triggers"] as string[]).filter((v) => typeof v === "string")
: [],
confidence_delta:
typeof r["confidence_delta"] === "number" ? (r["confidence_delta"] as number) : null,
alternatives: Array.isArray(r["alternatives"])
? (r["alternatives"] as string[]).filter((v) => typeof v === "string")
: [],
actor: typeof r["actor"] === "string" ? (r["actor"] as string) : "",
rationale: typeof r["rationale"] === "string" ? (r["rationale"] as string) : "",
reason_code: typeof r["reason_code"] === "string" ? (r["reason_code"] as string) : "",
idempotency_key: r["idempotency_key"] as string,
});
}
// ----- History query --------------------------------------------------------
export interface DecisionHistoryQuery {
/** Filter to a single subject id/wikilink. */
readonly subject?: string;
/** Opaque cursor from a prior page's `nextCursor`. */
readonly cursor?: string;
/** Page size; defaults to {@link DECISION_HISTORY_DEFAULT_LIMIT}. */
readonly limit?: number;
/**
* Keep only the receipts this answers true for, before the total and
* the page are taken, so a dropped receipt moves neither. Absent, every
* receipt is kept.
*/
readonly keep?: (receipt: DecisionChangeReceipt) => boolean;
}
export interface DecisionHistoryPage {
readonly receipts: ReadonlyArray<DecisionChangeReceipt>;
/** Exact count of receipts matching the filter (across all pages). */
readonly total: number;
/** Opaque cursor for the next page, or `null` when exhausted. */
readonly nextCursor: string | null;
}
/**
* The decisions history speaks the canonical core offset-cursor encoding
* (src/core/brain/offset-cursor.ts); its wire form (`o:<offset>` base64url)
* is unchanged since this surface shipped it first. A malformed cursor is
* still a `ReceiptError` on this surface's contract.
*/
function decodeReceiptCursor(cursor: string): number {
try {
return decodeOffsetCursor(cursor);
} catch {
throw new ReceiptError("receipt: malformed cursor");
}
}
/**
* Paginated, subject-filterable history over the receipt log. Returns the
* page, an opaque `nextCursor` (null when exhausted), and the exact total
* matching the filter. Read-only: never appends.
*/
export function queryDecisionChangeHistory(
vault: string,
query: DecisionHistoryQuery,
): DecisionHistoryPage {
const limit = query.limit ?? DECISION_HISTORY_DEFAULT_LIMIT;
if (!Number.isInteger(limit) || limit <= 0) {
throw new ReceiptError("receipt: limit must be a positive integer");
}
const offset = query.cursor !== undefined ? decodeReceiptCursor(query.cursor) : 0;
const read = readDecisionChangeReceipts(vault).receipts;
const all = query.keep === undefined ? read : read.filter(query.keep);
let matching = all;
if (query.subject !== undefined) {
// Read-side only: receipts store subjects in whichever shape their
// writer had on hand (bare id, wikilink, or vault-relative path), so
// both sides are normalized to the bare id before comparing.
const wanted = normalizeDecisionSubject(query.subject);
matching = all.filter((r) => normalizeDecisionSubject(r.subject) === wanted);
}
const total = matching.length;
const page = matching.slice(offset, offset + limit);
const nextOffset = offset + page.length;
const nextCursor = nextOffset < total ? encodeOffsetCursor(nextOffset) : null;
return Object.freeze({ receipts: page, total, nextCursor });
}