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
/**
* apply-evidence event appender.
*
* `apply-evidence` is the canonical durable signal that a preference was
* exercised against real work. It is the only log event that drives the
* `unconfirmed → confirmed` transition and the `applied_count` /
* `violated_count` / `last_evidence_at` counters that `dream` recomputes
* on every run.
*
* Surface:
*
* - {@link appendApplyEvidence} writes one apply-evidence entry to
* `Brain/log/<today>.md`. The file is created on the first event of
* the day; subsequent calls append. Returns the resolved log path
* and the ISO timestamp used in the heading.
*
* - {@link BrainPreferenceNotFoundError} is the typed failure surface
* for the "wrong pref_id" path. The CLI in Task 6 catches it and
* exits with code 2 (informative, not error). We deliberately use a
* distinct error class so callers can pattern-match on it without
* a `.message.includes()` regex.
*
* The check on the preference is intentionally cheap: we resolve the
* preference path under `Brain/preferences/<pref_id>.md` and verify it
* exists + parses. We don't update the preference file from here —
* `dream` is the only writer of preference frontmatter (counters,
* confidence, status); `apply-evidence` only records the event. That
* keeps the log as the single source of truth for evidence counts and
* lets `dream` stay deterministic from the log alone.
*/
import { existsSync } from "node:fs";
import { basename, join, relative } from "node:path";
import { vaultRelative } from "../path-safety.ts";
import { sanitiseTextField } from "../redactor.ts";
import {
computePayloadHash,
IdempotencyPayloadMismatchError,
lookupKey,
REMEMBER_KEY_STATUS,
rememberKey,
} from "./idempotency-ledger.ts";
import {
appendLogEvent,
logEventPrivacyContent,
type AppendLogEventResult,
type BrainLogEntry,
} from "./log.ts";
import { isDualWriteEnabled } from "../store/dual-write.ts";
import { routeWrite } from "../store/store-write.ts";
import { withLocalLock } from "../store/local-lock.ts";
import { storesStateDir } from "../store/store-paths.ts";
import { processDirsEnv } from "../platform-dirs.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { isPrivatePageFile, preferenceEvidenceRecord } from "../store/dual-write-records.ts";
import {
callerInput,
opaqueFields,
operationPrivacy,
type OperationPrivacy,
type PrivacyVerdict,
} from "../store/operation-privacy.ts";
import { loadPreference, parsePreference } from "./preference.ts";
import { preferencesStoreOnly, storePreferenceEntry } from "./preference-store.ts";
import { preferencePathOf, validateSlug } from "./paths.ts";
import { isoSecond } from "./time.ts";
import { checkRolePermission } from "./trust/check-role-permission.ts";
import { BRAIN_OPERATIONS, type BrainRole } from "./trust/role.ts";
import { renderPrefLink } from "./wikilink.ts";
import {
BRAIN_APPLY_OUTCOME,
BRAIN_APPLY_RESULT,
BRAIN_LOG_EVENT_KIND,
type BrainApplyOutcome,
type BrainApplyResult,
} from "./types.ts";
const ARTIFACT_MAX_LEN = 512;
const NOTE_MAX_LEN = 4096;
/**
* Thrown by {@link appendApplyEvidence} when the targeted preference
* does not exist on disk. The CLI surfaces this as exit code 2 (not an
* error per se — the agent referenced an unknown rule and the operator
* should learn about it without the run looking like a crash).
*/
export class BrainPreferenceNotFoundError extends Error {
readonly prefId: string;
readonly searchedPath: string;
constructor(prefId: string, searchedPath: string) {
super(
`preference not found: ${prefId}; expected ${searchedPath}. ` +
"Use `o2b brain query` to list active preferences.",
);
this.name = "BrainPreferenceNotFoundError";
this.prefId = prefId;
this.searchedPath = searchedPath;
}
}
/**
* Thrown when {@link appendApplyEvidence} is called with a role that
* is not permitted to record evidence (v0.10.16).
*/
export class BrainRolePermissionError extends Error {
readonly role: BrainRole;
constructor(role: BrainRole, reason: string) {
super(`apply-evidence permission denied for role '${role}': ${reason}`);
this.name = "BrainRolePermissionError";
this.role = role;
}
}
/** Input contract for {@link appendApplyEvidence}. */
export interface AppendApplyEvidenceInput {
/**
* Preference id, with or without the `pref-` prefix. Both
* `pref-foo` and `foo` are accepted so the CLI and MCP layers can
* be lenient about how callers spell the target.
*/
readonly pref_id: string;
/**
* Wikilink target of the artifact where the rule was applied
* (`[[Daily/2026.05.14#section]]`, `[[blog-header-draft]]`, …).
* The string is recorded verbatim — we do not validate the link
* resolves; the user's workflow chooses the convention.
*/
readonly artifact: string;
readonly result: BrainApplyResult;
readonly agent: string;
readonly note?: string;
/**
* Downstream outcome of the artifact the rule was applied to
* (t_d478df53). Optional and additive: `unknown` is treated like an
* absent outcome, only `success`/`failure` persist in the log.
*/
readonly outcome?: BrainApplyOutcome;
/**
* Client-supplied idempotency key (C1 / t_213f356b). Additive and
* optional: absent → byte-identical to the historical append path.
* When present, the appender hashes the semantic payload (pref id,
* artifact, result, agent, note, outcome) and consults the idempotency
* ledger before appending. A repeat with the same key + same payload is
* a deduped no-op (no second log row); the same key + a different
* payload throws {@link IdempotencyPayloadMismatchError}.
*/
readonly idempotency_key?: string;
}
export interface AppendApplyEvidenceOptions {
/**
* Override the wall clock. Defaults to `new Date()`. Tests pin this
* so the resulting log entry is byte-deterministic.
*/
readonly now?: Date;
/**
* Caller role (v0.10.16). When provided, the role-permission gate
* runs and rejects calls from roles that are not allowed to record
* evidence. Legacy callers that omit the field bypass the gate -
* the default is to preserve pre-v0.10.16 behaviour.
*/
readonly role?: BrainRole;
/**
* The vault-relative paths the caller may read. A preference file it
* may not read is refused with {@link BrainPreferenceNotFoundError}
* exactly as a missing one is, before anything is written. Absent,
* every preference counts.
*/
readonly readable?: (rel: string) => boolean;
/**
* The privacy verdict of an enclosing operation (a write batch), which
* every store record of this call inherits (`store/operation-privacy.ts`).
*/
readonly storePrivate?: PrivacyVerdict;
}
/**
* Does `prefFilePath` name a preference the caller may record evidence
* against? A file the caller may not read answers as a missing one.
*/
export function isApplyEvidenceTargetPresent(
vault: string | null,
prefFilePath: string,
readable: ((rel: string) => boolean) | undefined,
): boolean {
const present =
vault === null || preferencesStoreOnly(vault)
? loadPreference(vault, basename(prefFilePath, ".md").slice("pref-".length)) !== null
: existsSync(prefFilePath);
if (!present) return false;
// With no vault the path is already vault-relative.
return (
readable === undefined ||
readable(vault === null ? prefFilePath : vaultRelative(prefFilePath, vault))
);
}
export interface AppendApplyEvidenceResult {
/** ISO-8601 UTC timestamp written to the log heading. */
readonly logged_at: string;
/** Absolute path of the log file the event landed in. */
readonly log_path: string;
/**
* Set to `true` when an `idempotency_key` matched a prior append with an
* identical payload, so this call was a deduped no-op (no second row).
* The returned `logged_at`/`log_path` point at the ORIGINAL event.
* Absent on a normal append.
*/
readonly deduped?: boolean;
}
/** A validated evidence call: its target and the event body it appends. */
interface PreparedEvidence {
readonly prefFilePath: string;
readonly target: ReturnType<typeof parsePreference>;
/** The event body, as the call hands it to the log appender. */
readonly body: Record<string, string>;
}
/**
* Validate one evidence call and render the event body it appends. Shared
* by {@link appendApplyEvidence} and {@link applyEvidencePrivacy}, so the
* privacy a write batch judges before it commits is judged from the very
* body the append writes.
*/
function prepareEvidence(
vault: string | null,
input: AppendApplyEvidenceInput,
readable: ((rel: string) => boolean) | undefined,
): PreparedEvidence {
if (!input.pref_id || !input.pref_id.trim()) {
throw new Error("apply-evidence missing field: pref_id");
}
// Sanitise free-form fields up-front so a pure-control-char input
// falls into the "missing-field" branch instead of into YAML.
const artifact = sanitiseTextField(input.artifact, {
maxLen: ARTIFACT_MAX_LEN,
singleLine: true,
});
const note =
input.note !== undefined ? sanitiseTextField(input.note, { maxLen: NOTE_MAX_LEN }) : undefined;
if (!artifact || !artifact.trim()) {
throw new Error("apply-evidence missing field: artifact");
}
if (!input.agent || !input.agent.trim()) {
throw new Error("apply-evidence missing field: agent");
}
if (
input.result !== BRAIN_APPLY_RESULT.applied &&
input.result !== BRAIN_APPLY_RESULT.violated &&
input.result !== BRAIN_APPLY_RESULT.outdated
) {
throw new Error(
`apply-evidence field 'result' must be 'applied', 'violated', or 'outdated'; got ${JSON.stringify(input.result)}`,
);
}
if (
input.outcome !== undefined &&
input.outcome !== BRAIN_APPLY_OUTCOME.success &&
input.outcome !== BRAIN_APPLY_OUTCOME.failure &&
input.outcome !== BRAIN_APPLY_OUTCOME.unknown
) {
throw new Error(
`apply-evidence field 'outcome' must be 'success', 'failure', or 'unknown'; got ${JSON.stringify(input.outcome)}`,
);
}
// Resolve and validate the preference file. We accept both the bare
// slug (`foo`) and the prefixed id (`pref-foo`) for caller comfort.
const rawId = input.pref_id.trim();
const slug = rawId.startsWith("pref-") ? rawId.slice("pref-".length) : rawId;
if (!slug) {
throw new Error(`apply-evidence: invalid pref_id (empty slug): ${input.pref_id}`);
}
validateSlug(slug);
const prefFilePath = preferencePathOf(vault, slug);
if (!isApplyEvidenceTargetPresent(vault, prefFilePath, readable)) {
throw new BrainPreferenceNotFoundError(`pref-${slug}`, prefFilePath);
}
// Parse so a corrupted target produces a meaningful error rather
// than silently appending an evidence row that points at garbage.
// The parsed pref also supplies the principle used to title the
// wikilink we emit below.
// Once switched (or with no vault) the fold is the only source: a
// preference retired since the presence check is not found, and no
// page path is read.
const loaded = loadPreference(vault, slug);
if (loaded === null && (vault === null || preferencesStoreOnly(vault))) {
throw new BrainPreferenceNotFoundError(`pref-${slug}`, prefFilePath);
}
const target = loaded ?? parsePreference(prefFilePath);
const wikilink = renderPrefLink({ id: target.id, principle: target.principle });
// Render the canonical payload. Ordering is deliberate: the wikilink
// to the preference comes first so a human scrolling the log finds
// the target rule immediately; the result follows so the reader sees
// "what happened" before the optional note. Keys not present in the
// input are omitted so the file stays as small as possible.
const body: Record<string, string> = {
preference: wikilink,
artifact: artifact.trim(),
agent: input.agent.trim(),
result: input.result,
};
if (
input.outcome === BRAIN_APPLY_OUTCOME.success ||
input.outcome === BRAIN_APPLY_OUTCOME.failure
) {
body["outcome"] = input.outcome;
}
const trimmedNote = note?.trim();
if (trimmedNote) body["note"] = trimmedNote;
return { prefFilePath, target, body };
}
/**
* The privacy verdict of one evidence call (`store/operation-privacy.ts`):
* private when the target preference is private or cannot be judged, when
* the event body or any field of the caller's `input` (its idempotency
* key included) names a private or unresolvable page or carries a
* `<private>` region, or when `inherit` (an enclosing operation) is.
*/
function evidencePrivacy(
vault: string | null,
input: AppendApplyEvidenceInput,
prepared: PreparedEvidence,
inherit?: PrivacyVerdict,
): OperationPrivacy {
return operationPrivacy(vault, {
// The preference's page, or its records once switched (task 2.10).
target: () =>
preferencesStoreOnly(vault)
? (storePreferenceEntry(prepared.target.id.slice("pref-".length))?.private ?? true)
: isPrivatePageFile(prepared.prefFilePath),
content: [logEventPrivacyContent(prepared.body), callerInput(input, EVIDENCE_INPUT_OPAQUE)],
inherit: [inherit],
});
}
/** Opaque fields of an evidence call's input: its idempotency key. */
const EVIDENCE_INPUT_OPAQUE: ReadonlySet<string> = opaqueFields();
/**
* The privacy verdict {@link appendApplyEvidence} would give `input`, for
* an enclosing operation (a write batch) that judges itself before it
* commits. A call that would be refused cannot be judged and counts as
* private.
*/
export function applyEvidencePrivacy(
vault: string | null,
input: AppendApplyEvidenceInput,
readable?: (rel: string) => boolean,
): OperationPrivacy {
let prepared: PreparedEvidence;
try {
prepared = prepareEvidence(vault, input, readable);
} catch {
return () => true;
}
return evidencePrivacy(vault, input, prepared);
}
/**
* Append one `apply-evidence` event to today's log. Throws
* {@link BrainPreferenceNotFoundError} when the preference id does not
* resolve to a file under `Brain/preferences/`.
*
* The log file is created on the first event of the day (the appender
* inside `log.ts` handles that transparently). Subsequent calls on the
* same UTC day append.
*/
export function appendApplyEvidence(
vault: string | null,
input: AppendApplyEvidenceInput,
opts: AppendApplyEvidenceOptions = {},
): AppendApplyEvidenceResult {
if (opts.role !== undefined) {
const verdict = checkRolePermission(opts.role, BRAIN_OPERATIONS.evidence_record);
if (!verdict.allowed) {
throw new BrainRolePermissionError(opts.role, verdict.reason ?? "denied");
}
}
const prepared = prepareEvidence(vault, input, opts.readable);
// One privacy verdict for every store record this call writes: the log
// event, the idempotency receipt and the evidence record. It is judged
// once, before anything is appended, so it follows the preference as
// read here even if the file is rewritten or retired meanwhile. Judged
// only when the dual write is on (with it off nothing changes).
const privacy = evidencePrivacy(vault, input, prepared, opts.storePrivate);
if (isDualWriteEnabled() || preferencesStoreOnly(vault)) privacy();
// Every store record written from here on, by this call or by any
// writer it calls, carries this verdict (`store/operation-scope.ts`).
const idKey = input.idempotency_key?.trim();
return withOperationPrivacy(privacy, () =>
serialisedByKey(idKey, () => appendOnce(vault, input, prepared, privacy, idKey, opts.now)),
);
}
/**
* Run a keyed apply under one device-local lock, so two processes on
* this machine carrying the same idempotency key cannot both miss the
* consult and both append: the second sees the first's key and dedupes
* before it writes the log event or the evidence record (the fold counts
* evidence records by occurrence). A call with no key runs as is. Two
* devices racing on one key before their shards meet are the ledger's
* documented boundary (`idempotency-ledger.ts`).
*/
function serialisedByKey<T>(idKey: string | undefined, fn: () => T): T {
if (!idKey) return fn();
return withLocalLock(join(storesStateDir(processDirsEnv()), APPLY_EVIDENCE_LOCK), fn);
}
/** Device-local lock file of a keyed apply's consult-append-remember. */
const APPLY_EVIDENCE_LOCK = "apply-evidence-idempotency";
function appendOnce(
vault: string | null,
input: AppendApplyEvidenceInput,
prepared: PreparedEvidence,
privacy: OperationPrivacy,
idKey: string | undefined,
at: Date | undefined,
): AppendApplyEvidenceResult {
const { target, body } = prepared;
const now = at ?? new Date();
const timestamp = isoSecond(now);
// Idempotency consult (C1): a repeat with the same key + same payload
// dedupes (no second row); the same key + a different payload throws
// before appending. The hash covers the rendered event body — exactly
// what would land in the log.
let idContentHash: string | undefined;
if (idKey) {
idContentHash = computePayloadHash(body);
const existing = lookupKey(vault, idKey);
if (existing) {
if (existing.contentHash === idContentHash) {
const ref = (existing.ref ?? {}) as { logged_at?: string; log_path?: string };
return {
logged_at: ref.logged_at ?? timestamp,
log_path: ref.log_path ? vaultPath(vault, ref.log_path) : "",
deduped: true,
};
}
throw new IdempotencyPayloadMismatchError(idKey, existing.contentHash, idContentHash);
}
}
const entry: BrainLogEntry = {
timestamp,
eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
body,
};
const result: AppendLogEventResult = appendLogEvent(vault, entry, { storePrivate: privacy });
// Brain store dual write (task 1.11): the log event above is dual-written
// by the log appender; the evidence record feeds the preference fold's
// counters. Off by default, never fails this append.
// On a store-only machine (task 2.10) the record is written to the
// store only, and a store failure fails the call. It is written before
// the idempotency key is remembered: a failure then leaves no key, so
// a retry runs the whole path again instead of deduping onto an event
// whose evidence never reached the fold.
routeWrite({
legacy: () => undefined,
store: () =>
preferenceEvidenceRecord({
id: target.id,
result: input.result,
artifact: body["artifact"]!,
agent: body["agent"]!,
private: privacy(),
}),
context: { vault },
});
// Record the key AFTER the row lands so a future retry dedupes. Under a
// concurrent same-key race the unlocked lookupKey above can miss a rival
// write; rememberKey re-checks under its shard lock and returns the verdict,
// which we MUST act on (the ledger never throws — the writer decides).
if (idKey && idContentHash !== undefined) {
const remembered = rememberKey(vault, {
key: idKey,
contentHash: idContentHash,
createdAt: timestamp,
ref: {
logged_at: timestamp,
log_path: vault === null ? result.logPath : relative(vault, result.logPath),
},
private: privacy,
});
if (remembered.status === REMEMBER_KEY_STATUS.payload_mismatch) {
throw new IdempotencyPayloadMismatchError(
idKey,
remembered.record.contentHash,
idContentHash,
);
}
if (remembered.status === REMEMBER_KEY_STATUS.duplicate_match) {
// A rival process won the key with the same payload between our unlocked
// lookup and this locked record; report the winner's row as the deduped
// result instead of a second normal write.
const ref = (remembered.record.ref ?? {}) as { logged_at?: string; log_path?: string };
return {
logged_at: ref.logged_at ?? timestamp,
log_path: ref.log_path ? vaultPath(vault, ref.log_path) : result.logPath,
deduped: true,
};
}
}
return { logged_at: timestamp, log_path: result.logPath };
}
/** `rel` under `vault`; with no vault, the vault-relative name itself. */
function vaultPath(vault: string | null, rel: string): string {
return vault === null ? rel : join(vault, rel);
}