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
/**
* Runtime-state notice channel.
*
* Open Second Brain's health signals are otherwise pull-only (brain_doctor,
* brain_health, vault_health): the agent must poll to learn that semantic
* search fell back to lexical, that the index is not built or is rebuilding,
* or that the vault is read-only. This collector computes those transient
* conditions deterministically - no network, no LLM, no DB open - so they can
* ride the existing SessionStart injection surface (and vault_health) as a
* proactive push, letting the agent adjust behaviour without a diagnostic
* round-trip.
*
* Notices only exist while a real condition holds, so a healthy vault yields
* none and the injected context stays byte-identical. Scope is OSB's own
* subsystems (embeddings/index availability, read-only mode); it is not a
* third-party plugin notice bus and does not classify quota errors.
*
* The command a notice points at is a FIELD, not a sentence (no-dead-ends,
* task 3). It is resolved strictly through `next-step.ts`, so a condition
* whose code has no registered exit carries no key at all rather than a
* plausible command invented to make the shape uniform; four of the six
* conditions below are in exactly that position and say why at their own
* site. {@link renderRuntimeNotices} is the single place the command is
* rendered back into prose, for the two human surfaces (the SessionStart
* injection and the onboarding checklist) that share it.
*/
import { existsSync } from "node:fs";
import { join } from "node:path";
import lockfile from "proper-lockfile";
import { resolveSearchConfig } from "../search/index.ts";
import { checkVaultWriteable } from "../doctor.ts";
import { NEXT_COMMAND_KEY, nextCommandField, type NextCommandField } from "./next-step.ts";
import { BRAIN_ROOT_REL } from "./paths.ts";
import { brainConfigUnreadableReport } from "./policy.ts";
import { vaultMarkerAbsentNotice } from "./vault-identity.ts";
export type RuntimeNoticeSeverity = "info" | "warning";
/**
* One transient condition. The optional next command is spelled with the
* shared machine-readable key rather than a camel-cased twin because this
* record IS the wire shape on two surfaces - `o2b onboarding --json`
* serializes it whole, and `vault_health` projects it field for field - so
* a second spelling would be a second contract.
*/
export interface RuntimeNotice extends NextCommandField {
readonly code: string;
readonly severity: RuntimeNoticeSeverity;
readonly message: string;
}
/**
* Build one notice, resolving its next command from the diagnostics
* registry. Strict resolution: an unregistered code contributes no key,
* so the absence is visible instead of guessed at.
*/
function notice(code: string, severity: RuntimeNoticeSeverity, message: string): RuntimeNotice {
return { code, severity, message, ...nextCommandField(code) };
}
export interface RuntimeNoticeOptions {
readonly configPath?: string;
readonly env?: Record<string, string | undefined>;
}
/**
* Collect the current runtime-state notices for `vault`. Never throws: any
* probe failure is swallowed so the channel can be called from the fail-soft
* inject path. Returns an empty list when everything is nominal or when the
* channel is opted out via `OPEN_SECOND_BRAIN_RUNTIME_NOTICES`.
*/
export function collectRuntimeNotices(
vault: string,
opts: RuntimeNoticeOptions = {},
): RuntimeNotice[] {
const env = opts.env ?? process.env;
const optOut = env["OPEN_SECOND_BRAIN_RUNTIME_NOTICES"]?.trim().toLowerCase();
if (optOut === "false" || optOut === "0") return [];
const notices: RuntimeNotice[] = [];
// Vault writability: a read-only vault means every memory write will fail.
//
// No registered command: the two exits are an OS permission change on
// this root and a different `VAULT_DIR`, neither of them an `o2b` verb,
// and which one is right depends on which vault the operator meant. The
// message names both branches; the field stays absent rather than
// picking one.
try {
const writeable = checkVaultWriteable(vault);
if (!writeable.ok) {
notices.push(
notice(
"vault_read_only",
"warning",
`Vault is not writable, so memory writes will fail (${writeable.message}). Fix permissions on ${vault} or point VAULT_DIR at a writable vault.`,
),
);
}
} catch {
// best-effort
}
// Vault identity: a Brain tree with no identity marker cannot tell an
// old vault from a mis-resolved root, and the write guard can only warn
// about it (context-integrity-gates, Unit J). Gated on the tree already
// existing, because a root nothing has written to yet is not a wrong
// store - it is a vault waiting for `o2b brain init`, and nagging before
// that command runs would make the notice noise instead of signal.
//
// No registered command, and this one is the reason the field is
// optional rather than uniform. An absent marker is ambiguous BY
// CONSTRUCTION: `vault-identity.ts` documents that a cold-start
// mis-resolution - a typo in `VAULT_DIR` - is indistinguishable from
// the intended vault, because nothing durable records which vault the
// process meant. `o2b brain init` is the exit for one reading and
// materializes the wrong store under the other, so the conditional
// sentence the guard already writes ("...if it is the intended vault")
// is the honest form and a structural command would not be.
try {
if (existsSync(join(vault, BRAIN_ROOT_REL))) {
const absent = vaultMarkerAbsentNotice(vault);
if (absent !== null) {
notices.push(notice("vault_marker_absent", "warning", `${absent.detail} (${absent.path})`));
}
}
} catch {
// best-effort
}
// An unreadable `_brain.yaml`: every `load*ConfigSafe` reader falls
// back, and for the integrity gates that fallback is now the STRICT
// one rather than the defaults. Either way the operator's settings are
// not the ones in force, so the condition has to be visible instead of
// inferable from a gate that suddenly refuses.
//
// The sentence is `brainConfigUnreadableReport`'s, not this channel's:
// a delivery surface that degraded because of the same condition
// carries the same words, so an operator meets one fault and not two.
//
// No registered command: the repair is an edit to the YAML the parser
// just rejected, and no `o2b` verb performs it. The failure detail the
// report quotes is what the operator acts on; `o2b brain doctor` would
// only re-report the same line, which is a round-trip, not an exit.
try {
const report = brainConfigUnreadableReport(vault);
if (report !== null) {
notices.push(notice("brain_config_unreadable", "warning", report));
}
} catch {
// best-effort
}
// Search index availability + semantic degradation.
try {
const config = resolveSearchConfig({ vault, configPath: opts.configPath });
const dbPath = config.dbPath;
const indexExists = existsSync(dbPath);
if (!indexExists) {
// The read path self-heals: `openReadOrSelfHeal` catches
// INDEX_MISSING, builds the index and retries, so recall does not
// come back empty - it comes back late. The notice said the
// opposite until no-dead-ends (task 3) corrected it; what the
// command buys is paying that build now rather than on the first
// query.
notices.push(
notice(
"search_index_missing",
"info",
"Search index is not built yet, so the first recall builds it before returning " +
"(that call pays the full index build).",
),
);
} else if (reindexInProgress(dbPath)) {
// No registered command: the condition clears itself when the
// running rebuild finishes, and nothing an operator can type makes
// it clear sooner.
notices.push(
notice(
"reindex_in_progress",
"info",
"Search index is rebuilding; recent recall results may lag until it completes.",
),
);
}
const semantic = config.semantic;
const networked = semantic.provider !== "local" && semantic.provider !== "disabled";
if (semantic.enabled && networked && !semantic.apiKey) {
notices.push(
notice(
"semantic_degraded",
"warning",
"Semantic search is enabled but no embedding key resolved, so search has fallen back to lexical.",
),
);
}
} catch {
// best-effort
}
return notices;
}
/**
* A live reindex holds a heartbeated writer lock on the index path (see
* search/store.ts). Detecting a non-stale lock is the "reindex in progress"
* signal. Best-effort: any probe error means "not detectable", not a notice.
*/
function reindexInProgress(dbPath: string): boolean {
try {
return lockfile.checkSync(dbPath, { realpath: false });
} catch {
return false;
}
}
/**
* Label the command is rendered behind on the human surfaces. The
* spelling is the one the prose used to carry, so a notice whose text did
* not change renders byte-for-byte what it rendered when the command was
* part of the sentence - which matters because this block lands in an
* agent's SessionStart context, not only in a terminal.
*/
const COMMAND_LABEL = "Run:";
/** The ` Run: <command>` tail, or nothing when the code has no exit. */
function commandTail(entry: RuntimeNotice): string {
const command = entry[NEXT_COMMAND_KEY];
return command === undefined ? "" : ` ${COMMAND_LABEL} ${command}`;
}
/**
* Render notices as a compact injectable block; empty string when clean.
*
* This is the ONE place a structured command becomes prose again. Both
* human surfaces - the SessionStart injection and the onboarding
* checklist - render through here, so the machine-readable field and the
* sentence a person reads cannot drift apart the way two hand-written
* copies did.
*/
export function renderRuntimeNotices(notices: ReadonlyArray<RuntimeNotice>): string {
if (notices.length === 0) return "";
const lines = notices.map((n) => `- [${n.severity}] ${n.message}${commandTail(n)}`);
return `Runtime notices:\n${lines.join("\n")}`;
}