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-record note family (Belief lifecycle suite, Track B anchor,
* t_ac03214d).
*
* A decision is the highest-value operator memory: the choice made, the
* key assumption riding on it, a date to review whether it held, an
* (initially empty) outcome that hindsight backfills, and an optional
* pre-mortem ("how could this go wrong"). Each decision is a Markdown
* page under `Brain/decisions/decision-<slug>.md`: operator-readable in
* Obsidian, greppable, versionable - mirroring the `obligations.ts` and
* `health/thesis.ts` page models.
*
* The `review_date` maps onto the existing obligations engine: capturing
* a decision opens exactly one review obligation, idempotently (a second
* attempt on the same review slug is a no-op, never a duplicate). Outcome
* backfill is a logged mutation. Capturing a new decision can surface
* historically similar decisions with their recorded outcomes via the
* shared similarity machinery (`similarity.ts`) - deterministic,
* language-agnostic token overlap, no model call.
*
* Import direction: this module imports from obligations / paths / log /
* similarity / vault helpers, never the reverse.
*/
import { normalizeAgentArgument } from "../../agent-identity.ts";
import { resolveAgentName } from "../../config.ts";
import { sanitiseTextField } from "../../redactor.ts";
import { slugify } from "../../vault.ts";
import { appendLogEvent } from "../log.ts";
import { addObligation } from "../obligations.ts";
import { decisionPath, decisionsDir, obligationPath, validateIsoDate } from "../paths.ts";
import { BRAIN_DECISIONS_REL } from "../path-constants.ts";
import { jaccard, tokenise } from "../similarity.ts";
import { isoSecond } from "../time.ts";
import { BRAIN_LOG_EVENT_KIND, type BrainCommitmentTier } from "../types.ts";
import { readCommitmentTier, validateCommitmentTier } from "../commitment.ts";
import {
appendDecisionChangeReceipt,
DECISION_CHANGE_REASON,
RECEIPT_ABSENT_STATE,
type AppendReceiptInput,
} from "./receipts.ts";
import {
assertLaneWrite,
lanePageExists,
listLaneFiles,
parseLanePage,
writeLaneText,
} from "../../store/lane-pages.ts";
// ----- Constants ------------------------------------------------------------
/** Frontmatter `type` discriminator carried by every decision note. */
export const DECISION_TYPE = "decision";
/** Cap on the short prose frontmatter fields (chosen/assumption/etc). */
const FIELD_MAX_LEN = 512;
/** Cap on the decision title. */
const TITLE_MAX_LEN = 200;
/**
* Cadence stamped on the review obligation. A decision review is
* effectively a one-shot check; `yearly` is the least-nagging recurring
* cadence the obligations engine offers, so a completed-then-advanced
* obligation does not re-fire for a year.
*/
export const DECISION_REVIEW_CADENCE = "yearly";
/** Default jaccard floor for {@link findSimilarDecisions}. */
export const DECISION_SIMILARITY_THRESHOLD = 0.2;
/** Prefix applied to the review-obligation title. */
const REVIEW_OBLIGATION_TITLE_PREFIX = "Review decision:";
/** Inclusive lower bound of a decision rating (B2). */
export const DECISION_RATING_MIN = 1;
/** Inclusive upper bound of a decision rating (B2). */
export const DECISION_RATING_MAX = 5;
/** Receipt before/after state prefix for the chosen option (B4 trail). */
const RECEIPT_CHOSEN_PREFIX = "chosen:";
/** Receipt before/after state prefix for the hindsight outcome (B4 trail). */
const RECEIPT_OUTCOME_PREFIX = "outcome:";
/** Receipt before/after state prefix for the quality rating (B4 trail). */
const RECEIPT_RATING_PREFIX = "rating:";
/** Receipt state token for an unset rating (B4 trail). */
const RECEIPT_RATING_UNSET = "none";
// ----- Errors ---------------------------------------------------------------
/** Every failure path in this module raises this typed error. */
export class DecisionError extends Error {
constructor(message: string, options?: ErrorOptions) {
super(message, options);
this.name = "DecisionError";
}
}
// ----- Shapes ---------------------------------------------------------------
export interface DecisionRecord {
readonly slug: string;
/** Filename basename without `.md`. Equals `decision-<slug>`. */
readonly id: string;
/** Frontmatter type discriminator; always {@link DECISION_TYPE}. */
readonly type: typeof DECISION_TYPE;
/** The decision question / statement (drives the slug). */
readonly title: string;
/** The option that was chosen. */
readonly chosen: string;
/** The key assumption the decision rides on. */
readonly assumption: string;
/** Review date (`YYYY-MM-DD`), or null when none was captured. */
readonly reviewDate: string | null;
/** Hindsight outcome; empty until {@link backfillOutcome} runs. */
readonly outcome: string;
/** Optional pre-mortem ("how could this go wrong"). */
readonly premortem: string | null;
readonly createdAt: string;
readonly agent: string;
/**
* Quality self-assessment in [{@link DECISION_RATING_MIN},
* {@link DECISION_RATING_MAX}] (B2). `null` when the decision is
* unrated; an unrated decision omits the frontmatter key entirely so
* its on-disk shape is byte-identical to a B1 decision.
*/
readonly rating: number | null;
/** Free-form justification for the rating (B2); empty when unrated. */
readonly rationale: string;
/**
* Optional commitment tier (B3): `exploring | leaning | decided |
* locked`. `null` when unset; round-trips through frontmatter, emitted
* only when set so unset decisions stay byte-identical.
*/
readonly commitment: BrainCommitmentTier | null;
/** Free-form operator prose from the note body. */
readonly notes: string;
readonly path: string;
}
export interface RecordDecisionInput {
readonly title: string;
readonly chosen: string;
readonly assumption: string;
/** Review date (`YYYY-MM-DD`); opens exactly one review obligation. */
readonly reviewDate: string;
readonly premortem?: string;
readonly notes?: string;
/** Optional quality rating captured at record time (B2). */
readonly rating?: number;
/** Optional rationale for the rating (B2). */
readonly rationale?: string;
/** Optional commitment tier captured at record time (B3); validated on write. */
readonly commitment?: BrainCommitmentTier;
readonly agent: string;
readonly now?: Date;
readonly configPath?: string;
}
export interface RecordDecisionResult {
readonly record: DecisionRecord;
/** Slug of the opened review obligation. */
readonly reviewObligationSlug: string;
/** False when the review obligation already existed (idempotent). */
readonly obligationCreated: boolean;
}
/**
* The vault-relative paths the caller may read. A decision page it may
* not read is answered exactly as an absent one: skipped by every list,
* and refused by every single-slug read or write with the absent slug's
* error, before anything is written. Absent, every page may be read.
*/
export interface DecisionReadOptions {
readonly readable?: (rel: string) => boolean;
}
export interface BackfillOutcomeInput extends DecisionReadOptions {
readonly slug: string;
readonly outcome: string;
readonly agent?: string;
readonly now?: Date;
readonly configPath?: string;
}
export interface UpdateRatingInput extends DecisionReadOptions {
readonly slug: string;
readonly rating: number;
readonly rationale?: string;
readonly agent?: string;
readonly now?: Date;
readonly configPath?: string;
}
export interface SimilarDecision {
readonly slug: string;
readonly id: string;
readonly title: string;
readonly chosen: string;
readonly outcome: string;
readonly jaccard: number;
}
export interface SimilarDecisionQuery {
readonly title: string;
readonly chosen?: string;
/** Never return a decision with this slug (the one being captured). */
readonly excludeSlug?: string;
}
export interface FindSimilarDecisionsOptions extends DecisionReadOptions {
readonly threshold?: number;
readonly limit?: number;
}
// ----- Field helpers --------------------------------------------------------
function requireField(value: unknown, label: string): string {
if (typeof value !== "string") {
throw new DecisionError(`decision: ${label} is required`);
}
const cleaned = sanitiseTextField(value, {
maxLen: label === "title" ? TITLE_MAX_LEN : FIELD_MAX_LEN,
singleLine: true,
}).trim();
if (!cleaned) throw new DecisionError(`decision: ${label} is required`);
return cleaned;
}
function optionalField(value: unknown): string | null {
if (typeof value !== "string") return null;
const cleaned = sanitiseTextField(value, { maxLen: FIELD_MAX_LEN, singleLine: true }).trim();
return cleaned.length > 0 ? cleaned : null;
}
function requireReviewDate(value: string): string {
try {
return validateIsoDate(value);
} catch {
throw new DecisionError(`decision: review_date is not a valid calendar date: ${value}`);
}
}
/**
* Validate a rating: an integer in the inclusive
* [{@link DECISION_RATING_MIN}, {@link DECISION_RATING_MAX}] band.
*/
function requireRating(value: number): number {
if (!Number.isInteger(value) || value < DECISION_RATING_MIN || value > DECISION_RATING_MAX) {
throw new DecisionError(
`decision: rating must be an integer in [${DECISION_RATING_MIN}, ${DECISION_RATING_MAX}]`,
);
}
return value;
}
/**
* Parse a stored rating, tolerating a hand-edited value; null when
* absent or invalid. The flat frontmatter parser returns scalars as
* strings, so a numeric string (`"4"`) is accepted as well as a number.
*/
function parseRating(value: unknown): number | null {
let n: number;
if (typeof value === "number") n = value;
else if (typeof value === "string" && value.trim() !== "") n = Number(value);
else return null;
if (!Number.isInteger(n) || n < DECISION_RATING_MIN || n > DECISION_RATING_MAX) return null;
return n;
}
// ----- Change receipts (B4) -------------------------------------------------
/**
* Emit one decision-change receipt for a decision mutation. A mutation
* whose before-state equals its after-state changed no belief, so it
* emits nothing (an operator re-applying the same value is a no-op, in
* the spirit of the receipt idempotency key). Fail-soft otherwise: the
* decision note and its `decision-*` log event are authoritative, so an
* accountability-log hiccup must never fail the mutation itself. This
* mirrors the lifecycle supersede/tombstone receipt path.
*/
function emitDecisionChangeReceipt(vault: string, input: AppendReceiptInput): void {
if (input.before === input.after) return;
try {
appendDecisionChangeReceipt(vault, input);
} catch {
// Receipt is best-effort accountability; the decision note and its
// `decision-*` log event remain authoritative.
}
}
// ----- (De)serialization ----------------------------------------------------
function render(record: Omit<DecisionRecord, "path">): string {
const lines = [
"---",
`type: ${DECISION_TYPE}`,
`id: ${record.id}`,
`title: ${JSON.stringify(record.title)}`,
`chosen: ${JSON.stringify(record.chosen)}`,
`assumption: ${JSON.stringify(record.assumption)}`,
`review_date: ${record.reviewDate ?? ""}`,
`outcome: ${JSON.stringify(record.outcome)}`,
];
if (record.premortem !== null) lines.push(`premortem: ${JSON.stringify(record.premortem)}`);
// Rating fields are omitted entirely when unset so an unrated decision
// is byte-identical to a B1-era note (additive-only surface).
if (record.rating !== null) {
lines.push(`rating: ${record.rating}`);
lines.push(`rationale: ${JSON.stringify(record.rationale)}`);
}
// Commitment tier (B3): emitted only when set so an unset decision is
// byte-identical to a pre-B3 note.
if (record.commitment !== null) lines.push(`commitment: ${record.commitment}`);
lines.push(`created_at: ${record.createdAt}`);
lines.push(`agent: ${JSON.stringify(record.agent)}`);
lines.push("---", "", record.notes, "");
return lines.join("\n");
}
function parsePage(
vault: string,
slug: string,
readable: DecisionReadOptions["readable"],
): DecisionRecord | null {
const path = decisionPath(vault, slug);
if (!lanePageExists(vault, path)) return null;
if (readable !== undefined && !readable(decisionRel(slug))) return null;
const [meta, body] = parseLanePage(vault, path);
if (meta["type"] !== DECISION_TYPE) return null;
const reviewRaw = typeof meta["review_date"] === "string" ? meta["review_date"].trim() : "";
let reviewDate: string | null = null;
if (reviewRaw.length > 0) {
try {
reviewDate = validateIsoDate(reviewRaw);
} catch {
reviewDate = null;
}
}
const premortemRaw = typeof meta["premortem"] === "string" ? meta["premortem"] : "";
return Object.freeze({
slug,
id: `decision-${slug}`,
type: DECISION_TYPE,
title: typeof meta["title"] === "string" ? meta["title"] : slug,
chosen: typeof meta["chosen"] === "string" ? meta["chosen"] : "",
assumption: typeof meta["assumption"] === "string" ? meta["assumption"] : "",
reviewDate,
outcome: typeof meta["outcome"] === "string" ? meta["outcome"] : "",
premortem: premortemRaw.length > 0 ? premortemRaw : null,
createdAt: typeof meta["created_at"] === "string" ? meta["created_at"] : "",
agent: typeof meta["agent"] === "string" ? meta["agent"] : "",
rating: parseRating(meta["rating"]),
rationale: typeof meta["rationale"] === "string" ? meta["rationale"] : "",
commitment: readCommitmentTier(meta),
notes: body.trim(),
path,
});
}
/** The vault-relative POSIX path of one decision page, as the reach predicate reads it. */
function decisionRel(slug: string): string {
return `${BRAIN_DECISIONS_REL}/decision-${slug}.md`;
}
// ----- Review obligation ----------------------------------------------------
function reviewObligationTitle(decisionTitle: string): string {
return `${REVIEW_OBLIGATION_TITLE_PREFIX} ${decisionTitle}`;
}
/**
* Ensure the single review obligation for a decision exists, anchored at
* `reviewDate`. Idempotent: if the obligation slug already exists, this
* is a no-op returning `{ created: false }` rather than raising the
* obligations engine's duplicate error.
*/
export function ensureReviewObligation(
vault: string,
input: { title: string; reviewDate: string; agent: string; now?: Date },
): { slug: string; created: boolean } {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const obligationTitle = reviewObligationTitle(input.title);
const slug = slugify(obligationTitle);
if (lanePageExists(vault, obligationPath(vault, slug))) {
return { slug, created: false };
}
const page = addObligation(vault, {
title: obligationTitle,
cadence: DECISION_REVIEW_CADENCE,
agent: input.agent,
anchor: input.reviewDate,
...(input.now !== undefined ? { now: input.now } : {}),
});
return { slug: page.slug, created: true };
}
// ----- Capture --------------------------------------------------------------
/**
* Capture a decision: write the `type: decision` note, open its review
* obligation, and log a `decision-record` event. Refuses to clobber an
* existing decision slug (an update is a distinct, later operation).
*/
export function recordDecision(vault: string, input: RecordDecisionInput): RecordDecisionResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const title = requireField(input.title, "title");
const chosen = requireField(input.chosen, "chosen");
const assumption = requireField(input.assumption, "assumption");
const reviewDate = requireReviewDate(input.reviewDate);
const premortem = optionalField(input.premortem);
const rating = input.rating !== undefined ? requireRating(input.rating) : null;
const rationale =
rating !== null
? sanitiseTextField(input.rationale ?? "", { maxLen: FIELD_MAX_LEN, singleLine: true }).trim()
: "";
const commitment = validateCommitmentTier(input.commitment);
const now = input.now ?? new Date();
const slug = slugify(title);
if (lanePageExists(vault, decisionPath(vault, slug))) {
throw new DecisionError(`decision already exists: ${slug} (backfill or remove it first)`);
}
const explicitAgent = normalizeAgentArgument(input.agent ?? null);
const agent = explicitAgent ?? resolveAgentName(input.configPath);
const record: Omit<DecisionRecord, "path"> = {
slug,
id: `decision-${slug}`,
type: DECISION_TYPE,
title,
chosen,
assumption,
reviewDate,
outcome: "",
premortem,
createdAt: isoSecond(now),
agent,
rating,
rationale,
commitment,
notes: (input.notes ?? "").trim(),
};
const path = decisionPath(vault, slug);
writeLaneText(vault, path, render(record));
const review = ensureReviewObligation(vault, { title, reviewDate, agent, now });
appendLogEvent(vault, {
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.decisionRecord,
body: {
decision: `[[${record.id}]]`,
chosen,
review_date: reviewDate,
obligation: review.created ? review.slug : `${review.slug} (existing)`,
agent,
},
});
// B4 change trail: a decision's creation is a belief change with an
// absent before-state (no prior belief existed), per the closed schema.
emitDecisionChangeReceipt(vault, {
subject: `[[${record.id}]]`,
before: RECEIPT_ABSENT_STATE,
after: `${RECEIPT_CHOSEN_PREFIX}${chosen}`,
actor: agent,
rationale: assumption,
reasonCode: DECISION_CHANGE_REASON.record,
ts: isoSecond(now),
...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
});
return {
record: Object.freeze({ ...record, path }),
reviewObligationSlug: review.slug,
obligationCreated: review.created,
};
}
// ----- Outcome backfill -----------------------------------------------------
/**
* Backfill the `outcome` of an existing decision (a logged mutation).
* Preserves every other field and the body. Rejects an unknown slug or
* an empty outcome with a typed error.
*/
export function backfillOutcome(vault: string, input: BackfillOutcomeInput): DecisionRecord {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const slug = slugify(input.slug);
const prior = parsePage(vault, slug, input.readable);
if (prior === null) throw new DecisionError(`no decision: ${slug}`);
const outcome = sanitiseTextField(input.outcome, {
maxLen: FIELD_MAX_LEN,
singleLine: true,
}).trim();
if (!outcome) throw new DecisionError("decision: outcome is required for backfill");
const now = input.now ?? new Date();
const explicitAgent = normalizeAgentArgument(input.agent ?? null);
const agent = explicitAgent ?? resolveAgentName(input.configPath);
const { path: _path, ...rest } = prior;
const next: Omit<DecisionRecord, "path"> = { ...rest, outcome };
writeLaneText(vault, prior.path, render(next));
appendLogEvent(vault, {
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.decisionOutcome,
body: {
decision: `[[${prior.id}]]`,
outcome,
agent,
},
});
// B4 change trail: backfilling the outcome moves the belief state from
// the prior outcome (empty until the first backfill) to the new one.
emitDecisionChangeReceipt(vault, {
subject: `[[${prior.id}]]`,
before: `${RECEIPT_OUTCOME_PREFIX}${prior.outcome}`,
after: `${RECEIPT_OUTCOME_PREFIX}${outcome}`,
actor: agent,
reasonCode: DECISION_CHANGE_REASON.outcome,
ts: isoSecond(now),
...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
});
return Object.freeze({ ...next, path: prior.path });
}
// ----- Rating (B2) ----------------------------------------------------------
/**
* Set or change the `rating` (and optional `rationale`) of an existing
* decision (a logged mutation). Preserves every other field and the body.
* Rejects an unknown slug or an out-of-range rating with a typed error.
*/
export function updateRating(vault: string, input: UpdateRatingInput): DecisionRecord {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const slug = slugify(input.slug);
const prior = parsePage(vault, slug, input.readable);
if (prior === null) throw new DecisionError(`no decision: ${slug}`);
const rating = requireRating(input.rating);
const rationale =
input.rationale !== undefined
? sanitiseTextField(input.rationale, { maxLen: FIELD_MAX_LEN, singleLine: true }).trim()
: prior.rationale;
const now = input.now ?? new Date();
const explicitAgent = normalizeAgentArgument(input.agent ?? null);
const agent = explicitAgent ?? resolveAgentName(input.configPath);
const { path: _path, ...rest } = prior;
const next: Omit<DecisionRecord, "path"> = { ...rest, rating, rationale };
writeLaneText(vault, prior.path, render(next));
appendLogEvent(vault, {
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.decisionRating,
body: {
decision: `[[${prior.id}]]`,
rating: String(rating),
...(rationale ? { rationale } : {}),
agent,
},
});
// B4 change trail: rating is a belief-quality change; the before-state
// is the prior rating (`none` when previously unrated).
emitDecisionChangeReceipt(vault, {
subject: `[[${prior.id}]]`,
before: `${RECEIPT_RATING_PREFIX}${prior.rating ?? RECEIPT_RATING_UNSET}`,
after: `${RECEIPT_RATING_PREFIX}${rating}`,
actor: agent,
...(rationale ? { rationale } : {}),
reasonCode: DECISION_CHANGE_REASON.rating,
ts: isoSecond(now),
...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
});
return Object.freeze({ ...next, path: prior.path });
}
/**
* Every rated decision, sorted by descending rating (ties break on slug).
* Unrated decisions are excluded - this is the rated-capture list surface,
* separate from ordinary signal/preference recall.
*/
export function listRatedDecisions(
vault: string,
opts: DecisionReadOptions = {},
): DecisionRecord[] {
return listDecisions(vault, opts)
.filter((d) => d.rating !== null)
.toSorted((a, b) => (b.rating ?? 0) - (a.rating ?? 0) || a.slug.localeCompare(b.slug));
}
/**
* Read a specific set of decisions side by side for comparison, in the
* order requested. Unknown slugs are skipped (a comparison of what exists).
*/
export function compareDecisions(
vault: string,
slugs: ReadonlyArray<string>,
opts: DecisionReadOptions = {},
): DecisionRecord[] {
const out: DecisionRecord[] = [];
for (const slug of slugs) {
const page = parsePage(vault, slugify(slug), opts.readable);
if (page !== null) out.push(page);
}
return out;
}
// ----- Reads ----------------------------------------------------------------
/** One decision, or null. */
export function showDecision(
vault: string,
slug: string,
opts: DecisionReadOptions = {},
): DecisionRecord | null {
return parsePage(vault, slugify(slug), opts.readable);
}
/** Every decision, sorted by slug. */
export function listDecisions(vault: string, opts: DecisionReadOptions = {}): DecisionRecord[] {
const dir = decisionsDir(vault);
if (!lanePageExists(vault, dir)) return [];
const out: DecisionRecord[] = [];
for (const name of listLaneFiles(vault, dir, "")) {
if (!name.endsWith(".md") || !name.startsWith("decision-")) continue;
const slug = name.replace(/^decision-/u, "").replace(/\.md$/u, "");
const page = parsePage(vault, slug, opts.readable);
if (page !== null) out.push(page);
}
return out.toSorted((a, b) => a.slug.localeCompare(b.slug));
}
// ----- Similar-decision lookup ----------------------------------------------
/**
* Surface historically similar decisions with their recorded outcomes,
* ranked by descending token-overlap (jaccard) of the query's
* title+chosen against each stored decision's title+chosen. Deterministic
* and language-agnostic (shared `tokenise`/`jaccard`, no stopword list,
* no model). Ties break on slug for stable output.
*/
export function findSimilarDecisions(
vault: string,
query: SimilarDecisionQuery,
opts: FindSimilarDecisionsOptions = {},
): SimilarDecision[] {
const threshold = opts.threshold ?? DECISION_SIMILARITY_THRESHOLD;
const queryTokens = tokenise(`${query.title} ${query.chosen ?? ""}`);
if (queryTokens.size === 0) return [];
const out: SimilarDecision[] = [];
for (const decision of listDecisions(
vault,
opts.readable !== undefined ? { readable: opts.readable } : {},
)) {
if (query.excludeSlug !== undefined && decision.slug === query.excludeSlug) continue;
const tokens = tokenise(`${decision.title} ${decision.chosen}`);
const score = jaccard(queryTokens, tokens);
if (score < threshold) continue;
out.push({
slug: decision.slug,
id: decision.id,
title: decision.title,
chosen: decision.chosen,
outcome: decision.outcome,
jaccard: score,
});
}
out.sort((a, b) => b.jaccard - a.jaccard || a.slug.localeCompare(b.slug));
return opts.limit !== undefined ? out.slice(0, opts.limit) : out;
}