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_context` (task 3.19): the active-digest regeneration the agent
* context opens with, with the standing-rules and scoped-rules blocks it
* renders and the counts it reports. Split from `context-tools.ts`;
* registration happens through that module's registry, which preserves
* the public CONTEXT_TOOLS surface.
*/
import { existsSync, readFileSync } from "node:fs";
import {
brainDirsOf,
brainStandingRulesPath,
BRAIN_ACTIVE_FILE,
BRAIN_ROOT_REL,
} from "../../core/brain/paths.ts";
import {
readStandingRules,
renderStandingRules,
renderStandingRulesFailure,
type StandingRules,
} from "../../core/brain/standing-rules.ts";
import {
loadBrainConfig,
resolveScopedRulesMaxChars,
resolveStandingRulesMaxChars,
} from "../../core/brain/policy.ts";
import {
readScopedRules,
type ScopedRuleIdentity,
type ScopedRules,
} from "../../core/brain/scoped-rules.ts";
import { resolveHostScope, resolveProjectScope } from "../../core/brain/scope-identity.ts";
import type { BrainConfig } from "../../core/brain/types.ts";
import {
regenerateActive,
readerNarrowsActive,
renderActiveForReader,
type RegenerateActiveResult,
} from "../../core/brain/active.ts";
import {
compiledDigestPath,
digestsRenderedOnDemand,
} from "../../core/brain/compiled-digest-path.ts";
import { computeMaintenanceOverdueFlag } from "../../core/brain/status.ts";
import { TRANSPORT_REACH } from "../../core/graph/transport-reach.ts";
import { parseFrontmatter } from "../../core/vault.ts";
import { readVaultInstructionFile } from "../../core/brain/vault-instruction-file.ts";
import { readPinnedContext } from "../../core/brain/pinned.ts";
import { contextReach, contextVault, type ServerContext } from "../tool-contract.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { deliveryView } from "./reach-events.ts";
import { readableAtContextReachOrUndefined } from "./reach-readable.ts";
import { toolPath } from "./device-path.ts";
import {
appendPinnedToContextContent,
serializePinnedContext,
shapedPinnedContent,
} from "./context-pinned-tools.ts";
export type BrainContextCounts = RegenerateActiveResult["counts"];
export const EMPTY_CONTEXT_COUNTS: BrainContextCounts = {
confirmed: 0,
quarantine: 0,
retired_recent: 0,
most_applied_30d: 0,
};
/**
* Pull-bootstrap of `Brain/active.md` + the active-preference counts.
* Built for runtimes that have no `SessionStart` hook (Cursor, Aider,
* raw Claude API): one tool call gives the agent the same shortcut card
* the SessionStart-aware runtimes get injected automatically.
*
* Not a pure read: the bootstrap path calls `regenerateActive`, which
* writes `Brain/active.md` whenever the on-disk body is absent or
* stale, so the tool classifies `write` (write-mode-dominant,
* `tool-contract.ts`) and the stdio transport never runs two bootstrap
* calls beside each other on the concurrent read path.
*
* Behaviour matrix:
* - Brain/ absent → present:false, zero counts, and content
* carrying the standing-rules block or the
* statement that it could not be read (empty
* for the ordinary case, where there is no
* such file either).
* - Brain/ present, active.md absent → call regenerateActive (idempotent)
* and read the regenerated file.
* - Brain/ present, active.md fresh → idempotent regenerate leaves an
* equal body on disk; the on-disk
* body is returned verbatim.
*/
export async function toolBrainContext(ctx: ServerContext): Promise<Record<string, unknown>> {
// `null` on a server with no vault (design D14): the digest renders from
// the store's folds into the device-local cache, and there is no vault
// file to read (standing rules, scoped rules, the instruction file).
const vault = contextVault(ctx);
const dirs = brainDirsOf(vault);
// `Brain/active.md` on an unswitched machine; on a store-only one the
// device-local cache the digest is rendered into on demand (D14 item 7).
const activePath = compiledDigestPath(vault, "active");
const onDemand = digestsRenderedOnDemand(vault);
const pinned = readPinnedContext(vault);
// The request's delivery binding, resolved ONCE and used for the active
// body AND the pinned scratchpad beside it (delivery-trust, lane A): one
// frontmatter cache serves the whole assembly, instead of the pinned
// serializer building a second binding per call.
const delivery = deliveryView(ctx);
// Bounded to the single newest `Brain/log/` day - see
// `computeMaintenanceOverdueFlag`'s docblock for the cost bound. This
// is the always-loaded path, so the full `maintenance_debt` derivation
// on `computeBrainStatus` never runs here.
const maintenanceOverdue = computeMaintenanceOverdueFlag(vault, {
withholdsPrivate: contextReach(ctx) !== TRANSPORT_REACH.local,
});
// The operator's standing rules, resolved before anything else this
// surface assembles - INCLUDING the no-Brain return below. `brain_context`
// is the pull-mode twin of the SessionStart hook, so the constitution has
// to lead the content here for exactly the reason it leads the injected
// payload: on the error branch further down, which zeroes `content` and
// would otherwise hand a runtime the memory layer's failure and none of
// the rules that still govern it, and equally on the branch that reports
// `Brain/` as absent. That probe answers false for a directory it cannot
// TRAVERSE as well as one that is not there, and it was the one return
// path that said nothing at all about the rules - the last silent answer
// on a surface where every other path either carries the block or states
// why it could not be read.
const standing = vault === null ? NO_STANDING_BLOCK : readStandingBlock(vault);
// The scoped operator rules for the project, harness and host this
// server was launched for - local reach only, see `readScopedBlock`.
// Read beside the constitution, before the no-Brain return, for the
// same reason: the rules govern a session whatever the memory layer did.
const scoped = readScopedBlock(ctx);
// A store-only machine keeps its memory in the store, `Brain/` or not.
if (!onDemand && !existsSync(dirs.brain)) {
return {
vault_path: vaultPathField(ctx),
present: false,
active_path: activePath,
content: prependBlock(standing.text, prependBlock(scoped?.text ?? "", "")),
counts: EMPTY_CONTEXT_COUNTS,
generated_at: null,
pinned: serializePinnedContext(ctx, pinned, undefined, undefined, {
shapeBody: true,
delivery,
}),
maintenance_overdue: maintenanceOverdue,
...standingRulesField(ctx, standing),
...scopedRulesField(scoped),
};
}
let counts: BrainContextCounts = EMPTY_CONTEXT_COUNTS;
let error: string | undefined;
try {
// The SHARED file is regenerated unscoped, always. `active.md` is one
// file for the whole vault - injected into every agent's SessionStart
// by `hooks/active-inject.ts` and regenerated unscoped by the
// `osb://preferences/active` resource - so narrowing the WRITE to this
// caller would make it thrash and could drop an agent's own memories
// from its session start (context-integrity-gates, A3).
counts = regenerateActive(vault).counts;
} catch (err) {
error = (err as Error)?.message ?? String(err);
}
// After a successful regenerateActive, active.md is guaranteed to
// exist (the function either wrote it or confirmed an equal body
// already on disk). A read failure here is an unrelated filesystem
// race, not a missing-file branch — handle it in the same `error`
// slot the regenerate failure uses.
let content = "";
let generatedAt: string | null = null;
if (!error) {
try {
content = readFileSync(activePath, "utf8");
const [meta] = parseFrontmatter(activePath);
const v = meta["generated_at"];
if (typeof v === "string" && v.trim().length > 0) {
generatedAt = v;
}
} catch (err) {
error = (err as Error)?.message ?? String(err);
content = "";
generatedAt = null;
}
}
// What this ONE caller is handed, not what is on disk, answers at its
// reach and under the owner gate. This surface takes no arguments, so
// `ServerContext.agentName` is its only source of identity and the
// minted reach its only source of distance. A preference or retired
// record the caller cannot read is absent from its digest - principle,
// counts and most-applied entry alike. A local caller with no enforced
// owner scope keeps the file's own bytes; any other caller gets the
// reader render, decided on its reach rather than on what is withheld,
// and stamped with the generation already on disk.
if (!error) {
const readable = readableAtContextReachOrUndefined(ctx);
const reader = {
...(readable !== undefined ? { readable } : {}),
restricted: contextReach(ctx) !== TRANSPORT_REACH.local,
...(ctx.agentName !== undefined ? { agentScope: ctx.agentName } : {}),
};
if (readerNarrowsActive(vault, reader)) {
const narrowed = renderActiveForReader(vault, reader);
content = narrowed.document;
counts = narrowed.counts;
}
}
// Constitution first, then the scoped rules, then the memory body -
// and the body is shaped BEFORE the assembly (delivery-trust, lane A):
// the fence wraps the stored-record bytes only. The constitution and
// the scoped rules are the operator's own voice delivered local-only,
// and the pinned scratchpad shapes through the same binding beside
// this assembly, so neither slips past the fence the body carries.
// An unfetchable body has nothing to fence: the pinned scratchpad's
// shaper skips empty bodies, and the main body answers the same way
// instead of wrapping an empty block in the fence.
if (content.length > 0) {
content = delivery.shape(content, `${BRAIN_ROOT_REL}/${BRAIN_ACTIVE_FILE}`);
}
content = prependBlock(standing.text, prependBlock(scoped?.text ?? "", content));
content = appendPinnedToContextContent(content, shapedPinnedContent(ctx, pinned, delivery));
// Optional vault-root instruction file (v0.10.17). Absent file =
// field omitted so hosts that strip unknown fields stay
// byte-identical.
//
// A THROW IS NOT AN ABSENCE. This used to be `catch { null }`, which
// put an operator configuration error - an absolute path, a `..`
// segment, an empty name - and an unreadable file on the same wire as
// a vault that simply has no instruction file: the field vanished and
// nothing said why. The reason now rides its own key, so the
// enrichment stays best-effort without being silent.
let vaultInstruction: ReturnType<typeof readVaultInstructionFile> = null;
let vaultInstructionError: string | undefined;
try {
vaultInstruction = vault === null ? null : readVaultInstructionFile(vault);
} catch (err) {
vaultInstructionError = (err as Error)?.message ?? String(err);
}
return {
vault_path: vaultPathField(ctx),
present: true,
active_path: activePath,
content,
counts,
generated_at: generatedAt,
pinned: serializePinnedContext(ctx, pinned, undefined, undefined, {
shapeBody: true,
delivery,
}),
maintenance_overdue: maintenanceOverdue,
...(error ? { error } : {}),
...standingRulesField(ctx, standing),
...scopedRulesField(scoped),
...(vaultInstruction
? {
vault_instruction: {
path: vaultInstruction.path,
content: vaultInstruction.content,
lines: vaultInstruction.lines,
},
}
: {}),
...(vaultInstructionError !== undefined
? { vault_instruction_error: vaultInstructionError }
: {}),
};
}
/**
* The standing-rules block and the record behind it, or neither.
*
* The two travel together because the response reports them in two
* different places - the block is prepended to `content`, the record
* becomes the `standing_rules` key - and a read that FAILED produces a
* block but no record: there is no path/content/truncated triple to
* report for bytes nobody could read, and the block itself is what says
* so in words the agent will read.
*/
export interface StandingBlock {
readonly text: string;
readonly rules: StandingRules | null;
}
export const NO_STANDING_BLOCK: StandingBlock = Object.freeze({ text: "", rules: null });
export function readStandingBlock(vault: string): StandingBlock {
const path = brainStandingRulesPath(vault);
let cfg: BrainConfig | null = null;
try {
cfg = loadBrainConfig(vault);
} catch {
// A `_brain.yaml` this surface cannot read resolves the cap to its
// default; the config failure itself surfaces through the `error`
// slot that the regenerate arm above already populates.
}
try {
const rules = readStandingRules(vault, { maxChars: resolveStandingRulesMaxChars(cfg) });
if (rules === null) return NO_STANDING_BLOCK;
return Object.freeze({ text: renderStandingRules(rules), rules });
} catch (err) {
return Object.freeze({ text: renderStandingRulesFailure(path, err), rules: null });
}
}
/**
* The optional `standing_rules` key, or nothing.
*
* Both return shapes spread it from here so the two cannot disagree about
* when the key appears. It is omitted for a vault whose operator wrote no
* rules AND for a read that failed - the failure has no path/content/
* truncated triple to report, and the block inside `content` is what says
* so in words.
*/
export function standingRulesField(
ctx: ServerContext,
standing: StandingBlock,
): Record<string, unknown> {
if (standing.rules === null) return {};
return {
standing_rules: {
path: toolPath(ctx, standing.rules.path),
content: standing.rules.text,
truncated: standing.rules.truncated,
},
};
}
/** Put a block at the head of the content, or leave the content alone. */
export function prependBlock(block: string, content: string): string {
if (block.length === 0) return content;
const trimmed = content.trimStart();
return trimmed.length === 0 ? `${block}\n` : `${block}\n\n${trimmed}`;
}
/**
* The scoped operator rules rendered for this server's scope, or nothing.
*
* LOCAL REACH ONLY. The scope is resolved from facts about the process
* that serves the call - the directory it was launched in, the harness
* its registration names, the device it runs on - and at remote reach
* none of them describes the caller. So at remote reach nothing is read
* at all: not the files, not the pointer, not the device id, and the
* answer is byte-identical whether or not any scoped file exists.
*
* The identity comes from {@link ServerContext.ruleScope} and the device
* id; no argument of this tool can name it (the tool takes none).
*/
export function readScopedBlock(ctx: ServerContext): ScopedRules | null {
if (contextReach(ctx) !== TRANSPORT_REACH.local) return null;
// Scoped rules are vault files; a server with no vault has none.
if (contextVault(ctx) === null) return null;
let host: { readonly host: string | null; readonly unreadable: boolean };
try {
host = resolveHostScope(ctx.configPath ?? undefined);
} catch {
// A device id that cannot be resolved for any other reason (a config
// home that cannot be created, say) must not take the bootstrap
// surface down with it. It matches no host file, and the block says
// so when there is a host file it could have matched.
host = { host: null, unreadable: true };
}
const identity: ScopedRuleIdentity = {
project: resolveProjectScope(ctx.ruleScope?.workspaceDir ?? null, ctx.vault),
harness: ctx.ruleScope?.harness ?? null,
host: host.host,
};
let rules: ScopedRules;
try {
rules = readScopedRules(ctx.vault, identity, {
maxChars: scopedRulesMaxChars(ctx.vault),
hostUnreadable: host.unreadable,
});
} catch {
// The reader renders every per-file failure as an `UNAVAILABLE:` line
// and does not throw for one; anything that still escapes it must not
// take the constitution and the memory layer down with the scoped block.
return null;
}
return rules.text.length === 0 ? null : rules;
}
/**
* The configured cap, or its default when `_brain.yaml` cannot be read
* (that failure surfaces through the regenerate arm's `error` slot, as
* for the constitution's cap).
*/
export function scopedRulesMaxChars(vault: string): number {
let cfg: BrainConfig | null = null;
try {
cfg = loadBrainConfig(vault);
} catch {
// absorbed - see above
}
return resolveScopedRulesMaxChars(cfg);
}
/**
* The optional `scoped_rules` key, or nothing: present only when a file
* matched or the host notice applies, so a vault with no scoped rules -
* and every remote caller - keeps today's bytes.
*/
export function scopedRulesField(scoped: ScopedRules | null): Record<string, unknown> {
if (scoped === null) return {};
return {
scoped_rules: {
scope: {
project: scoped.identity.project,
harness: scoped.identity.harness,
host: scoped.identity.host,
},
files: scoped.files.map((file) => ({
path: file.path,
axis: file.axis,
truncated: file.truncated,
})),
},
};
}