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
/**
* The decision ledger (write-side-trust, Task 2).
*
* The queryable record of which rule allowed, asked or denied which
* operation: JSONL month/device shards under `Brain/logs/decisions/`, on
* the idempotency-ledger model. The per-device shard is the Syncthing
* answer - two machines never append to one file - and the merged read
* orders by (timestamp, shard id, line), so every device replays the same
* sequence no matter the order the shards arrived in.
*
* The append contract is absolute: a failed append NEVER throws. The
* ledger rides behind gates that must refuse or stage a write even when
* accountability cannot be recorded, so every failure - a malformed
* timestamp, an unwritable directory, a lock another writer holds - comes
* back as `{ logged: false, audit_reason }` for the caller to surface.
* Nothing here is silent: the audit reason is the caller's evidence.
*
* LEAF MODULE like its sibling `document.ts`: it imports the shared shard
* grammar and the Brain root name, and nothing that reaches back into the
* gates, so a guard can record a refusal without importing the layer the
* refusal came from.
*/
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import lockfile from "proper-lockfile";
import { ensureInsideVault } from "../../path-safety.ts";
import {
JSONL_LEDGER_EXT,
listShardedFiles,
mergeShardedRows,
resolveAppendShardId,
shardedFileName,
type LedgerShardGrammar,
type ShardedRow,
} from "../ledger-shards.ts";
import { BRAIN_ROOT_REL } from "../path-constants.ts";
import { legacyVaultOf } from "../no-vault.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import type { PermissionAction } from "./document.ts";
import { readLedgerRows } from "../../store/read/ledger-rows.ts";
import { routeWrite } from "../../store/store-write.ts";
import { DUAL_WRITE_LEDGERS, ledgerRowRecord } from "../../store/dual-write-records.ts";
/** Month-sharded JSONL root under `Brain/logs/`, beside the idempotency ledger. */
const DECISIONS_REL = `${BRAIN_ROOT_REL}/logs/decisions`;
/** Shard base: one file per UTC month, per device. */
const MONTH_BASE = "\\d{4}-\\d{2}";
const MONTH_RE = new RegExp(`^${MONTH_BASE}$`);
/** The ledger's file-name layout, handed to the shared shard grammar. */
export const DECISIONS_GRAMMAR: LedgerShardGrammar = Object.freeze({
base: MONTH_BASE,
extensions: Object.freeze([JSONL_LEDGER_EXT]),
});
/**
* One durable accountability row. `action` narrows to the permission
* vocabulary plus `resolution` - the row a staged document's apply or
* reject lands. `verdict` stays a plain string so gate modes and refusal
* tokens can appear beside allow/ask/deny; `source` names the deciding
* rule (an entry id, an agent or role, `default`, or a gate key).
*/
export interface DecisionLedgerRow {
ts: string;
actor: string;
via: string;
action: PermissionAction | "resolution";
target: string;
verdict: string;
source: string;
reason: string;
tool?: string;
correlation_id?: string;
}
/** The append outcome. `logged: false` always carries `audit_reason`. */
export interface DecisionLedgerAppendResult {
logged: boolean;
audit_reason?: string;
}
/** Every field a filter may narrow by; absent fields match everything. */
export interface DecisionLedgerFilter {
actor?: string;
action?: string;
verdict?: string;
target?: string;
/** Inclusive lower bound on `ts` (ISO-8601 compares as a string). */
since?: string;
/** Inclusive upper bound on `ts`. */
until?: string;
/** Applied after the deterministic sort, never during it. */
limit?: number;
}
/**
* The directory every decision shard lives in. Exported so the state
* surface inventory and the CLI resolve this ledger's location through
* the module that owns it.
*/
export function decisionLedgerDir(vault: string): string {
return ensureInsideVault(join(vault, DECISIONS_REL), vault);
}
/**
* One month's shard for one device: `<month>[.<shardId>].jsonl`. The
* append path derives its shard file through this; the query side lists
* the directory instead of precomputing names.
*/
export function decisionLedgerShardPath(month: string, shardId: string): string {
if (!MONTH_RE.test(month)) throw new Error(`invalid decision ledger month: ${month}`);
return shardedFileName(month, shardId, JSONL_LEDGER_EXT);
}
/**
* Append one row to this device's shard for the row's month.
*
* Never throws. The vault-identity guard runs INSIDE the failure net: a
* guard refusal means the row must not be written where it was aimed, and
* refusing-with-a-reason is exactly the append contract - the caller
* still gets its verdict through and carries the reason.
*/
export function appendDecisionLedger(
vault: string | null,
row: DecisionLedgerRow,
): DecisionLedgerAppendResult {
try {
const ts = requireTimestamp(row.ts);
const month = monthOf(ts);
const stored = stripEmptyOptionals(row);
// One `permissions` ledger row on a store-only machine (design D14
// item 1), this device's month shard plus the dual write otherwise. A
// store failure is caught below like any other and carried as the
// audit reason.
routeWrite({
legacy: () => {
const root = legacyVaultOf(vault, "appendDecisionLedger");
assertVaultIdentityForWrite(root);
const shardId = resolveAppendShardId();
const dir = decisionLedgerDir(root);
mkdirSync(dir, { recursive: true });
const shardPath = join(dir, decisionLedgerShardPath(month, shardId));
withShardLock(shardPath, () => {
writeFileSync(shardPath, `${JSON.stringify(stored)}\n`, {
encoding: "utf8",
flag: "a",
});
});
},
store: () => ledgerRowRecord(DUAL_WRITE_LEDGERS.permissions, stored, "private-when-held"),
context: { vault },
});
return { logged: true };
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
return { logged: false, audit_reason: `decision ledger append failed: ${message}` };
}
}
/**
* Every row the vault holds, merged across shards into the one order
* every device agrees on - (timestamp, shard id, line) - then narrowed by
* `filter`. An empty vault answers `[]` and creates nothing.
*
* A shard that cannot be READ propagates: an unreadable shard read as an
* empty one would answer "this write was never gated", which is the one
* wrong answer an accountability ledger must never give. A malformed LINE
* is skipped, on the idempotency-ledger precedent: history stays legible
* around a torn line instead of disappearing behind it.
*/
export function queryDecisionLedger(
vault: string | null,
filter: DecisionLedgerFilter = {},
): DecisionLedgerRow[] {
// One source decision (the read facade): the `permissions` ledger rows
// on a store-only machine (design D14 item 1), the merged shards on an
// unswitched one, which are already in the agreed order and are kept as
// they were read. The store rows, in fold order, are ordered by `ts`
// (ties keep fold order); a store row with no string `ts` cannot be
// placed and is not a decision row.
let legacy = false;
const rows = readLedgerRows<DecisionLedgerRow>(
DUAL_WRITE_LEDGERS.permissions,
() => {
legacy = true;
return readLegacyDecisionRows(legacyVaultOf(vault, "queryDecisionLedger"));
},
{ vault },
// As an unreadable legacy shard throws: never "this write was never gated".
{ strict: true },
);
const ordered = legacy
? rows
: rows
.filter((row) => row !== null && typeof row === "object" && typeof row.ts === "string")
.toSorted((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
return ordered.filter((row) => matches(row, filter)).slice(0, positiveLimit(filter));
}
/** The decision rows of an unswitched vault, merged across its shards. */
function readLegacyDecisionRows(vault: string): DecisionLedgerRow[] {
const dir = decisionLedgerDir(vault);
const shards = listShardedFiles(dir, DECISIONS_GRAMMAR);
if (shards.length === 0) return [];
const sharded: Array<ShardedRow<DecisionLedgerRow>> = [];
for (const shard of shards) {
let text: string;
try {
text = readShardText(vault, shard.path);
} catch (err) {
if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
throw err;
}
for (const [line, content] of text.split("\n").entries()) {
if (content.trim() === "") continue;
try {
sharded.push({
value: JSON.parse(content) as DecisionLedgerRow,
shardId: shard.shardId,
line,
});
} catch {
continue;
}
}
}
return mergeShardedRows(sharded, (row) => row.ts);
}
// ----- internals -------------------------------------------------------------
function readShardText(vault: string, path: string): string {
return readFileSync(ensureInsideVault(path, vault), "utf8");
}
function requireTimestamp(ts: string): string {
if (typeof ts !== "string" || !MONTH_RE.test(ts.slice(0, 7)) || ts.length < 7) {
throw new Error(`row ts must start with YYYY-MM; got ${JSON.stringify(ts)}`);
}
return ts;
}
function monthOf(ts: string): string {
return ts.slice(0, 7);
}
/**
* Serialise the append across processes: proper-lockfile on the shard
* path, with the bounded retry the secrets store's writer lock uses. The
* sync lockfile API has no retry option, so contention spins briefly
* before the caller sees the failure as an audit reason.
*/
function withShardLock(shardPath: string, fn: () => void): void {
const maxAttempts = 20;
let release: (() => void) | null = null;
let lastError: unknown;
for (let attempt = 0; attempt < maxAttempts && release === null; attempt++) {
try {
release = lockfile.lockSync(shardPath, { stale: 10_000, realpath: false });
} catch (exc) {
if ((exc as NodeJS.ErrnoException).code !== "ELOCKED") throw exc;
lastError = exc;
if (attempt < maxAttempts - 1) Bun.sleepSync(25);
}
}
if (release === null) {
const msg = lastError instanceof Error ? lastError.message : String(lastError);
throw new Error(`another writer holds the decision ledger shard lock: ${msg}`);
}
try {
fn();
} finally {
void release();
}
}
function stripEmptyOptionals(row: DecisionLedgerRow): DecisionLedgerRow {
return {
...row,
...(row.tool !== undefined ? { tool: row.tool } : {}),
...(row.correlation_id !== undefined ? { correlation_id: row.correlation_id } : {}),
};
}
function matches(row: DecisionLedgerRow, filter: DecisionLedgerFilter): boolean {
if (filter.actor !== undefined && row.actor !== filter.actor) return false;
if (filter.action !== undefined && row.action !== filter.action) return false;
if (filter.verdict !== undefined && row.verdict !== filter.verdict) return false;
if (filter.target !== undefined && row.target !== filter.target) return false;
if (filter.since !== undefined && row.ts < filter.since) return false;
if (filter.until !== undefined && row.ts > filter.until) return false;
return true;
}
/** A filter without a limit reads everything; a nonsense limit reads nothing extra. */
function positiveLimit(filter: DecisionLedgerFilter): number {
if (filter.limit === undefined) return Number.POSITIVE_INFINITY;
return filter.limit > 0 ? filter.limit : 0;
}