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
/**
* Brain operational status snapshot.
*
* One function: {@link computeBrainStatus} walks `Brain/` and returns
* counts, last-activity timestamps, a `maintenance_debt` block, and a
* single sanity flag. Pure read β nothing is mutated, nothing is parsed
* deeply (we cap I/O at `readdirSync` for counts and one `parseLogDay`
* per log file for timestamps and for the debt count).
*
* Used by:
*
* - the MCP `second_brain_status` tool (extended `brain` field)
* - the MCP resource `osb://status` (markdown render)
* - the MCP `brain_context` tool, which reads only the cheap, bounded
* `computeMaintenanceOverdueFlag` below β never this whole function
* β because it is the always-loaded reader (see that function's
* docblock for the cost bound).
*
* Callers that want the timestamps but not the counts can read either
* field independently β the shape is shallow.
*
* ## `maintenance_debt` (nothing-writes-silently, Unit D)
*
* DERIVED, not counted: there is no write-time counter and no
* STATE_SURFACES row backing this block. It is recomputed on every
* call from the same `Brain/log/` JSONL shards `scanLogTimestamps`
* already reads to find `last_dream_at`, so it cannot desync from the
* log and carries no write-path coupling.
*
* The field is named `log_events_since_dream`, not `writes_since_dream`,
* because that is what it measures and nothing more. `write-batch.ts`
* β the executor behind `brain_create_note`, `brain_update_note`,
* `brain_append_note`, and the note ops of `brain_write_batch` β never
* calls `appendLogEvent`; a caller-named note write leaves no log event
* to count. Calling this field "writes since dream" would be a false
* label on a true number, which is exactly the dishonesty this wave
* removes. It counts Brain LOG events (dream/feedback/apply-evidence/
* retire/promote/β¦ β the full {@link BRAIN_LOG_EVENT_KIND} vocabulary),
* a real and useful signal of unreviewed lifecycle activity, just not
* the one its old provisional name would have implied.
*
* Two fields the card asked for are deliberately absent, not forgotten:
*
* - `open_conflicts` needs a semantic-health run
* (`health/reconcile.ts`) to produce a `SemanticHealthReport`; that
* report is not already computed on this path and running it here
* would make every `second_brain_status` call pay for a health
* pass. Measured too expensive for a status snapshot; callers that
* want it run `brain_health` / the reconcile report directly.
* - `pending_triggers` was investigated against
* `src/core/brain/triggers/store.ts`. Its only readers,
* `readTriggers`/`listTriggers`, fully parse frontmatter AND every
* body section of EVERY `.md` file under `Brain/triggers/` before a
* status filter is even applied β there is no status-only or
* count-only accessor β and terminal triggers (acted / dismissed /
* expired / suppressed) are never pruned from that directory, so
* the read cost grows with the vault's entire trigger history, not
* with the currently-open count. Not the cheap count this block
* requires; measured too expensive, not forgotten.
*/
import { legacyVaultOf } from "./no-vault.ts";
import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";
import { memorySource, signalPageRaw, storePagesIn } from "./memory-pages.ts";
import { parseFrontmatter } from "../vault.ts";
import { brainDirs, snapshotsDir } from "./paths.ts";
import type { BrainLogEntry } from "./log.ts";
import { storeLogDays, withLogReadPass } from "./log-days.ts";
import { withoutPrivateEntries } from "./log-events-at-reach.ts";
import { readStoreLogEvents } from "../store/read/log-events.ts";
import { listLogDates, readLogDay } from "./log-jsonl.ts";
import { loadBrainConfig } from "./policy.ts";
import { parseSignal, parseStoreSignal } from "./signal.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "./types.ts";
import { lessonApprovalCounts, type LessonApprovalCounts } from "./lessons-promotion.ts";
// ----- Public types --------------------------------------------------------
export interface BrainStatusCounts {
readonly inbox: number;
readonly inbox_processed: number;
/** Signals in `inbox/archived/` (left the contradiction window unconsumed). */
readonly inbox_archived: number;
readonly preferences: number;
readonly preferences_by_status: Readonly<Record<string, number>>;
readonly retired: number;
readonly log_days: number;
readonly snapshots: number;
}
/**
* Whether `log_events_since_dream` is counted against a real dream
* boundary or reports the whole log because no boundary exists yet.
* `never_dreamed` is a distinct state from "zero events" β see the
* module docblock.
*/
export const MAINTENANCE_DEBT_STATUS = Object.freeze({
neverDreamed: "never_dreamed",
counted: "counted",
/**
* At least one log shard in the counted window could not be read, or
* held lines the reader could not parse, so the figure is a LOWER
* BOUND. Distinct from `counted` because the number an operator acts
* on is the one place a partial walk must not pass for a total.
*/
undercounted: "undercounted",
} as const);
export type MaintenanceDebtStatus =
(typeof MAINTENANCE_DEBT_STATUS)[keyof typeof MAINTENANCE_DEBT_STATUS];
/** See the "`maintenance_debt`" section of this module's docblock. */
export interface MaintenanceDebt {
readonly status: MaintenanceDebtStatus;
readonly log_events_since_dream: number;
}
const NEVER_DREAMED_DEBT: MaintenanceDebt = Object.freeze({
status: MAINTENANCE_DEBT_STATUS.neverDreamed,
log_events_since_dream: 0,
});
export interface BrainStatusSnapshot {
/** Whether `<vault>/Brain/` exists at all. */
readonly present: boolean;
readonly counts: BrainStatusCounts;
readonly last_dream_at: string | null;
readonly last_apply_evidence_at: string | null;
readonly maintenance_debt: MaintenanceDebt;
readonly sanity: {
/**
* Number of signals in `inbox/` whose `created_at` predates
* `now - dream.unconfirmed_window_days`. A non-zero value means
* dream hasn't been run for at least an entire trial window and
* the signals risk silent expiry.
*/
readonly signals_awaiting_dream: number;
};
/**
* Lesson-promotion approval counts (t_1e952e43): the decisions
* currently in force plus how many approved rows went stale,
* carried by the snapshot the MCP status tool already returns -
* report-only, no new surface minted for them. Fail-soft: a
* damaged ledger answers zeros and names itself in `read_error`;
* doctor is the surface for the damage itself.
*/
readonly lessons: LessonApprovalCounts & {
/** Present only when the approvals ledger could not be read. */
readonly read_error?: string;
};
}
/** The lessons counts block for a vault with no Brain layer. */
const LESSONS_COUNTS_ABSENT: LessonApprovalCounts = Object.freeze({
approved: 0,
denied: 0,
stale: 0,
});
/**
* The fail-soft read_error the snapshot carries when the approvals
* ledger cannot be read. Deliberately a fixed, generalized sentence:
* the ledger reader's error messages embed the ledger's absolute path,
* and machine paths stay out of MCP output - doctor is the surface that
* names the cause and the recovery in operator-facing output.
*/
const LESSONS_LEDGER_READ_ERROR =
"lessons-approvals.json could not be read (the ledger is damaged or unusable); " +
"o2b doctor names the cause and the recovery";
/**
* Read the lessons counts fail-soft: the doctor is the surface for a
* damaged ledger, the status snapshot answers with zeros and names
* itself, because an MCP consumer must not lose the whole brain block
* over one unreadable file.
*/
function lessonsCountsSafe(vault: string): LessonApprovalCounts & {
readonly read_error?: string;
} {
try {
return lessonApprovalCounts(vault);
} catch {
return { ...LESSONS_COUNTS_ABSENT, read_error: LESSONS_LEDGER_READ_ERROR };
}
}
export interface ComputeBrainStatusOptions {
/** Wall clock for staleness math. Defaults to `new Date()`. */
readonly now?: Date;
/**
* The caller is below local reach: the log days, the last dream and
* apply-evidence times and the maintenance debt are computed as if the
* events of the store's `private` partition did not exist. Default false.
*/
readonly withholdsPrivate?: boolean;
}
// ----- Public API ----------------------------------------------------------
export function computeBrainStatus(
vault: string,
opts: ComputeBrainStatusOptions = {},
): BrainStatusSnapshot {
// One read pass: the counts, the log timestamps and the maintenance debt
// each walk the log, and a store-only machine reads its log once.
return withLogReadPass(() => computeBrainStatusInPass(vault, opts));
}
function computeBrainStatusInPass(
vault: string,
opts: ComputeBrainStatusOptions,
): BrainStatusSnapshot {
const dirs = brainDirs(vault);
// A store-only machine keeps its memory records in the store (task
// 2.10): the brain is present when the store is, with or without the
// legacy tree.
const source = memorySource(vault);
if (source === "none" || (source === "legacy" && !existsSync(dirs.brain))) {
return Object.freeze({
present: false,
lessons: LESSONS_COUNTS_ABSENT,
counts: {
inbox: 0,
inbox_processed: 0,
inbox_archived: 0,
preferences: 0,
preferences_by_status: Object.freeze({}),
retired: 0,
log_days: 0,
snapshots: 0,
},
last_dream_at: null,
last_apply_evidence_at: null,
maintenance_debt: NEVER_DREAMED_DEBT,
sanity: { signals_awaiting_dream: 0 },
});
}
const withholds = opts.withholdsPrivate === true;
const counts = source === "store" ? countStoreArtifacts(vault, withholds) : countArtifacts(vault);
const { lastDreamAt, lastApplyEvidenceAt } = scanLogTimestamps(vault, withholds);
const signalsAwaitingDream = countSignalsAwaitingDream(
vault,
opts.now ?? new Date(),
source === "store",
);
const maintenanceDebt = computeMaintenanceDebt(vault, lastDreamAt, withholds);
return Object.freeze({
present: true,
counts,
lessons: lessonsCountsSafe(vault),
last_dream_at: lastDreamAt,
last_apply_evidence_at: lastApplyEvidenceAt,
maintenance_debt: maintenanceDebt,
sanity: Object.freeze({ signals_awaiting_dream: signalsAwaitingDream }),
});
}
/**
* Cheap, bounded proxy for `maintenance_debt` fit for the always-loaded
* `brain_context` path.
*
* Cost bound: at most one {@link listLogDates} call (a `readdirSync` of
* `Brain/log/` plus filename parsing β no file content is read) and, if
* any date exists, one {@link readLogDay} call for the SINGLE newest
* date. That is O(1) in the number of log days regardless of how much
* history the vault holds β `computeMaintenanceDebt` below, in
* contrast, walks every day at or after `last_dream_at` (all of them,
* for a never-dreamed vault) and MUST NOT run on this path.
*
* Returns `null` when there is no log history yet, when the newest day's
* shard(s) exist but could not be read, and when the newest day holds no
* readable event at all β all three are "unknown", never a false
* `false` and never a `true` invented out of an empty or unparsable
* file. Returns `true` when the newest log day has at least one event
* and none of them is a `dream` event, `false` when it has a `dream`
* event. A `dream` event is decisive even beside a warning: it was read,
* and nothing unread can unsay it. This is a same-day signal only: a vault that
* dreamed yesterday and logged something unrelated today still reads
* `true`. Callers that need the precise count read
* `maintenance_debt.log_events_since_dream` from `computeBrainStatus`
* instead (`second_brain_status` / `osb://status`).
*/
export function computeMaintenanceOverdueFlag(
vault: string | null,
opts: { readonly withholdsPrivate?: boolean } = {},
): boolean | null {
const withholds = opts.withholdsPrivate === true;
const log = recentStatusLog(vault, withholds) ?? statusLog(vault, withholds);
if (log === null) return null;
const newest = log.dates.at(-1);
if (newest === undefined) return null;
let day;
try {
day = log.day(newest);
} catch {
// Same tolerance as `scanLogTimestamps`: an unreadable day is
// reported as unknown, not silently folded into a boolean answer.
return null;
}
if (day.entries.some((e) => e.eventType === BRAIN_LOG_EVENT_KIND.dream)) return false;
// No dream event among the events that were read. That is only an
// answer when the read was whole and had something in it: an empty day
// and a day whose bytes did not parse are both "nothing to judge", and
// `true` there would report overdue maintenance out of a file nobody
// could read.
if (day.entries.length === 0 || day.warnings.length > 0) return null;
return true;
}
// ----- Implementation ------------------------------------------------------
function countArtifacts(vault: string): BrainStatusCounts {
const dirs = brainDirs(vault);
const inbox = countMd(dirs.inbox);
const inbox_processed = countMd(dirs.processed);
const inbox_archived = countMd(dirs.archived);
const retired = countMd(dirs.retired);
// Shard-aware: count distinct DAYS, not files (several shards share a day).
const log_days = listLogDates(vault).length;
const snapshots = countZst(snapshotsDir(vault));
// Per-status preference counts: read frontmatter line `status:` only
// β no full parse β to keep this cheap. Unknown values bucket under
// `unknown` so the doctor's parse errors are still visible upstream.
const preferences_by_status: Record<string, number> = {};
let preferences = 0;
if (existsSync(dirs.preferences)) {
for (const name of readdirSync(dirs.preferences)) {
if (!name.endsWith(".md")) continue;
if (!name.startsWith("pref-")) continue;
preferences++;
const status = readFrontmatterStatus(join(dirs.preferences, name));
preferences_by_status[status] = (preferences_by_status[status] ?? 0) + 1;
}
}
// Always include the canonical bucket names with 0 so consumers
// don't need to defensively `?? 0`.
for (const s of Object.values(BRAIN_PREFERENCE_STATUS)) {
preferences_by_status[s] = preferences_by_status[s] ?? 0;
}
return {
inbox,
inbox_processed,
inbox_archived,
preferences,
preferences_by_status: Object.freeze(preferences_by_status),
retired,
log_days,
snapshots,
};
}
/**
* {@link countArtifacts} on a store-only machine: the fold's records
* counted by the folder their page sat in, the preferences bucketed by
* their status. The log days and the snapshots are not memory records
* and are counted where they are.
*/
function countStoreArtifacts(vault: string, withholdsPrivate: boolean): BrainStatusCounts {
const dirs = brainDirs(vault);
const inFolder = (dir: string): number => storePagesIn(vault, dir).length;
const preferences_by_status: Record<string, number> = {};
let preferences = 0;
for (const page of storePagesIn(vault, dirs.preferences)) {
if (!page.id.startsWith("pref-")) continue;
preferences++;
const value = page.meta["_status"];
const status = typeof value === "string" && value.trim() !== "" ? value.trim() : "unknown";
preferences_by_status[status] = (preferences_by_status[status] ?? 0) + 1;
}
for (const s of Object.values(BRAIN_PREFERENCE_STATUS)) {
preferences_by_status[s] = preferences_by_status[s] ?? 0;
}
return {
inbox: inFolder(dirs.inbox),
inbox_processed: inFolder(dirs.processed),
inbox_archived: inFolder(dirs.archived),
preferences,
preferences_by_status: Object.freeze(preferences_by_status),
retired: inFolder(dirs.retired),
log_days: statusLog(vault, withholdsPrivate)?.dates.length ?? 0,
// The snapshot module's folder: the device-local state once switched.
snapshots: countZst(snapshotsDir(vault)),
};
}
/** The log as the status readers walk it: dates, and one day's events with its warnings. */
interface StatusLog {
readonly dates: ReadonlyArray<string>;
day(date: string): {
readonly entries: ReadonlyArray<BrainLogEntry>;
readonly warnings: ReadonlyArray<unknown>;
};
}
/** Days of the store log the overdue flag looks at before it reads the whole log. */
const RECENT_LOG_DAYS = 31;
/**
* The last {@link RECENT_LOG_DAYS} days of a store-only machine's log, or
* `null` when the machine reads day files or the window holds no event
* (the caller then reads the whole log), so the always-loaded overdue
* flag reads a bounded window, not the store's whole history. The window
* runs one day past today's UTC date: an entry is filed by the date its
* own timestamp spells, and one a device whose clock runs ahead wrote can
* already name tomorrow; the whole-log read has no upper bound either.
*/
function recentStatusLog(vault: string | null, withholdsPrivate: boolean): StatusLog | null {
const now = new Date();
const from = new Date(now.getTime() - RECENT_LOG_DAYS * 86_400_000);
const to = new Date(now.getTime() + 86_400_000);
const stored = readStoreLogEvents(
{ from: from.toISOString().slice(0, 10), to: to.toISOString().slice(0, 10) },
{ vault },
);
if (stored === null) return null;
// Below local reach a private event is not there, and a day it alone
// filled is not a log day.
const shown = withoutPrivateEntries(
stored.map((s) => s.entry),
withholdsPrivate,
);
if (shown.length === 0) return null;
const byDate = new Map<string, BrainLogEntry[]>();
for (const entry of shown) {
const date = entry.timestamp.slice(0, 10);
const day = byDate.get(date);
if (day === undefined) byDate.set(date, [entry]);
else day.push(entry);
}
return {
dates: [...byDate.keys()].toSorted(),
day: (date) => ({ entries: byDate.get(date) ?? [], warnings: [] }),
};
}
/**
* The log of `vault`: the day files on an unswitched machine (`null` when
* `Brain/log/` is absent), the store's `log-event` records on a store-only
* one (task 2.10), where a day carries no read warning.
*/
function statusLog(vault: string | null, withholdsPrivate = false): StatusLog | null {
const stored = storeLogDays(vault);
if (stored !== null) {
// Below local reach a private event is not there, and a day it alone
// filled is not a log day. Day files carry no mark.
const days = stored
.map((d) => ({ date: d.date, entries: withoutPrivateEntries(d.entries, withholdsPrivate) }))
.filter((d) => d.entries.length > 0 || !withholdsPrivate);
const byDate = new Map(days.map((d) => [d.date, d.entries] as const));
return {
dates: days.map((d) => d.date),
day: (date) => ({ entries: byDate.get(date) ?? [], warnings: [] }),
};
}
const root = legacyVaultOf(vault, "statusLog");
if (!existsSync(brainDirs(root).log)) return null;
return { dates: listLogDates(root), day: (date) => readLogDay(root, date) };
}
function countMd(dir: string): number {
if (!existsSync(dir)) return 0;
let n = 0;
for (const name of readdirSync(dir)) {
if (name.endsWith(".md")) n++;
}
return n;
}
function countZst(dir: string): number {
if (!existsSync(dir)) return 0;
let n = 0;
for (const name of readdirSync(dir)) {
if (name.endsWith(".tar.zst")) n++;
}
return n;
}
function readFrontmatterStatus(path: string): string {
// Use the canonical frontmatter parser instead of a regex sniff so
// quoted values (`_status: "confirmed"`) and other legal YAML
// shapes round-trip correctly. Files we can't parse bucket under
// `unknown` β doctor surfaces them as schema errors elsewhere.
try {
const [meta] = parseFrontmatter(path);
const value = meta["_status"];
if (typeof value !== "string") return "unknown";
const trimmed = value.trim();
return trimmed.length > 0 ? trimmed : "unknown";
} catch {
return "unknown";
}
}
function scanLogTimestamps(
vault: string,
withholdsPrivate: boolean,
): {
lastDreamAt: string | null;
lastApplyEvidenceAt: string | null;
} {
const log = statusLog(vault, withholdsPrivate);
if (log === null) return { lastDreamAt: null, lastApplyEvidenceAt: null };
const days = log.dates.toReversed(); // newest day first
let lastDreamAt: string | null = null;
let lastApplyEvidenceAt: string | null = null;
for (const date of days) {
// We only need the most-recent timestamp of each kind, so once
// both are set we can stop scanning older files.
let entries;
try {
entries = log.day(date).entries;
} catch {
continue;
}
for (let i = entries.length - 1; i >= 0; i--) {
const e = entries[i]!;
if (lastDreamAt === null && e.eventType === BRAIN_LOG_EVENT_KIND.dream) {
lastDreamAt = e.timestamp;
}
if (lastApplyEvidenceAt === null && e.eventType === BRAIN_LOG_EVENT_KIND.applyEvidence) {
lastApplyEvidenceAt = e.timestamp;
}
if (lastDreamAt !== null && lastApplyEvidenceAt !== null) break;
}
if (lastDreamAt !== null && lastApplyEvidenceAt !== null) break;
}
return { lastDreamAt, lastApplyEvidenceAt };
}
/**
* Derive `maintenance_debt` from the JSONL log shards, AFTER
* `last_dream_at` has already been resolved by {@link scanLogTimestamps}.
* No stored counter, no STATE_SURFACES row β see the module docblock.
*
* `lastDreamAt === null` (never dreamed) counts every event ever
* logged, because there is no dream boundary to count "since". A real
* `last_dream_at` counts only events with a strictly later timestamp β
* and a shard in that window that could not be read, or a line in it
* that could not be parsed, makes the answer `undercounted`: the number
* is then a floor, and the sibling flag's discipline (never a confident
* answer over an incomplete read) applies to the precise figure too.
*
* the dream event itself is the boundary, not a countable event β and
* walks days newest-first, stopping as soon as a day predates the
* dream's own day, so the scan is bounded to "since the last dream",
* not the whole log history, on every vault that HAS dreamed.
*/
function computeMaintenanceDebt(
vault: string,
lastDreamAt: string | null,
withholdsPrivate: boolean,
): MaintenanceDebt {
const log = statusLog(vault, withholdsPrivate);
if (log === null) return NEVER_DREAMED_DEBT;
const cutoffMs = lastDreamAt !== null ? Date.parse(lastDreamAt) : null;
const cutoffDate = lastDreamAt !== null ? lastDreamAt.slice(0, 10) : null;
const days = log.dates.toReversed(); // newest day first
let count = 0;
let complete = true;
for (const date of days) {
// Every earlier day is entirely pre-dream once we're past the
// dream's own day β no need to open its shards at all.
if (cutoffDate !== null && date < cutoffDate) break;
let entries;
try {
const day = log.day(date);
entries = day.entries;
// A shard that would not open, or a line that would not parse:
// either way events this window contains are absent from `count`,
// and the figure below is a floor rather than the count it looks
// like. Recorded, not aborted β the events that WERE read are
// still the operator's best available number.
if (day.warnings.length > 0) complete = false;
} catch {
// Same tolerance as scanLogTimestamps: skip the day rather than
// abort the snapshot β but never silently, see above.
complete = false;
continue;
}
for (const e of entries) {
if (cutoffMs !== null) {
const ts = Date.parse(e.timestamp);
if (!Number.isFinite(ts) || ts <= cutoffMs) continue;
}
count++;
}
}
return Object.freeze({
status: !complete
? MAINTENANCE_DEBT_STATUS.undercounted
: lastDreamAt === null
? MAINTENANCE_DEBT_STATUS.neverDreamed
: MAINTENANCE_DEBT_STATUS.counted,
log_events_since_dream: count,
});
}
function countSignalsAwaitingDream(vault: string, now: Date, fromStore: boolean): number {
const dirs = brainDirs(vault);
if (!fromStore && !existsSync(dirs.inbox)) return 0;
let windowDays: number;
try {
windowDays = loadBrainConfig(vault).dream.unconfirmed_window_days;
} catch {
return 0; // Config absent: doctor will flag; status reports 0.
}
const cutoffMs = now.getTime() - windowDays * 24 * 3600 * 1000;
let stale = 0;
if (fromStore) {
for (const page of storePagesIn(vault, dirs.inbox)) {
if (!page.id.startsWith("sig-")) continue;
let createdAtMs: number;
try {
createdAtMs = Date.parse(
parseStoreSignal(page.path, page.meta, signalPageRaw(page)).created_at,
);
} catch {
continue;
}
if (Number.isFinite(createdAtMs) && createdAtMs < cutoffMs) stale++;
}
return stale;
}
for (const name of readdirSync(dirs.inbox)) {
if (!name.endsWith(".md")) continue;
if (!name.startsWith("sig-")) continue;
// Read the authoritative `created_at` from frontmatter β filename
// is a hint but the timestamp is the source of truth (slug
// collisions and manual `mv` operations can desync the two).
let createdAtMs: number;
try {
createdAtMs = Date.parse(parseSignal(join(dirs.inbox, name)).created_at);
} catch {
continue; // Unparseable signal β doctor's domain, not status's.
}
if (!Number.isFinite(createdAtMs)) continue;
if (createdAtMs < cutoffMs) stale++;
}
return stale;
}