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 budgeted active-context assembly shared by both injection lanes
* (context-injection-pipeline).
*
* hooks/active-inject.ts puts the lanes together into the session-start
* preamble; hooks/subagent-inject.ts composes the same three lanes into
* the subagent carrier's payload. This module is the single code path
* behind both: the injection limits (the injection budget and the two
* rules caps), the scoped operator rules for this project and device,
* and the budgeted `Brain/active.md` + `Brain/lessons.md` body with the
* runtime notices ahead of it. One assembly means the carrier's payload
* and the session-start digest can never disagree about what the
* operator's context says or how it was rationed.
*
* The {@link InjectionMeter} (hooks/lib/standing-block.ts) threads
* through every producer here: per-source attribution stops existing at
* the join, so each sub-body is recorded while it is still a separate
* string. The session-start lane reads the meter for its context
* receipt; the carrier passes one because the assembly requires it and
* never reads it back.
*
* ABSENCE, FAILURE AND BUDGET stay where active-inject.ts put them. An
* absent file contributes nothing; a genuine read error THROWS so the
* session-start lane's fail-open loader can degrade to its last-good
* cache - the carrier, which has no cache, catches and degrades to an
* empty memory lane. The budget core's tier ladder degrades oversized
* sections automatically.
*/
import { existsSync, readFileSync } from "node:fs";
import { parseFrontmatterText } from "../../src/core/vault.ts";
import { activeDigestPathForRead } from "../../src/core/brain/active.ts";
import { lessonsDigestPathForRead } from "../../src/core/brain/lessons.ts";
import { budgetActiveBody, isTruncationNoticeOnly } from "../../src/core/brain/active-budget.ts";
import {
neutralizeUntrustedText,
untrustedBindingFramingHeader,
} from "../../src/core/brain/untrusted-source.ts";
import {
INJECT_BUDGET_CHARS_DEFAULT,
loadBrainConfig,
resolveScopedRulesMaxChars,
resolveStandingRulesMaxChars,
} from "../../src/core/brain/policy.ts";
import {
readScopedRules,
SCOPED_RULES_HEADER,
SCOPED_RULES_NOTICE_RESERVE,
} from "../../src/core/brain/scoped-rules.ts";
import { resolveHostScope, resolveProjectScope } from "../../src/core/brain/scope-identity.ts";
import {
collectRuntimeNotices,
renderRuntimeNotices,
} from "../../src/core/brain/runtime-notices.ts";
import { LANE_BUDGETED, LANE_UNBUDGETED, type InjectionMeter } from "./standing-block.ts";
import {
RECEIPT_ITEM_ACTIVE_BODY,
RECEIPT_ITEM_LESSONS_BODY,
RECEIPT_ITEM_SCOPED_RULES,
} from "../../src/core/brain/context-receipts.ts";
import type { BrainConfig } from "../../src/core/brain/types.ts";
/** Sub-body identifiers recorded per injection. Structural, not content-derived. */
export const SOURCE_SCOPED_RULES = RECEIPT_ITEM_SCOPED_RULES;
export const SOURCE_RUNTIME_NOTICES = "runtime-notices";
export const SOURCE_ACTIVE_BODY = RECEIPT_ITEM_ACTIVE_BODY;
export const SOURCE_LESSONS_BODY = RECEIPT_ITEM_LESSONS_BODY;
/** The memory sub-bodies, in the order `assembleActiveContext` joins them. */
export const MEMORY_SOURCES: ReadonlySet<string> = new Set([
SOURCE_RUNTIME_NOTICES,
SOURCE_ACTIVE_BODY,
SOURCE_LESSONS_BODY,
]);
/** Blank line between two injected blocks. */
export const BLOCK_SEPARATOR = "\n\n";
/** Join the non-empty blocks in order; an all-empty list yields "". */
export function joinBlocks(blocks: ReadonlyArray<string>): string {
return blocks.filter((block) => block.length > 0).join(BLOCK_SEPARATOR);
}
/**
* Set one budgeted memory body under the light untrusted framing header:
* the header line, then the body. A full fence is deliberately not used
* here - the wrapper pair would be charged to `inject_budget_chars` and
* the tier ladder would answer by evicting sections - so the provenance
* rides as the shared one-line header instead. The clause is the MEMORY
* lanes' binding clause, not the foreign lanes' records-not-instructions
* disclaimer: these bodies ARE the product's rules lane, and a preamble
* telling the model to read them as data would have it ignore the
* preferences the lane exists to deliver. The header line IS part of the
* metered source, so per-source attribution names the guarded bytes.
*/
function frameMemoryBody(origin: string, body: string): string {
return `${untrustedBindingFramingHeader(origin)}\n${body}`;
}
/**
* The characters one framed body costs beyond its inner body: the header
* line plus the newline that carries the body. Charged against the
* injection budget before the tier ladder runs (the recall-inject
* fenceOverhead precedent), so the ladder never evicts a section merely
* to pay for the framing.
*/
function framingOverhead(origin: string): number {
return untrustedBindingFramingHeader(origin).length + 1;
}
/** A fresh, empty meter for one assembly run. */
export function createInjectionMeter(configuredBudgetChars: number): InjectionMeter {
return {
sources: [],
configuredBudgetChars,
budgetChars: null,
scopedRulesChars: 0,
};
}
/**
* The two character ceilings this hook applies, resolved once.
*
* They are separate numbers because they govern separate lanes: the
* injection budget rations what the agent recalled about itself, the
* standing-rules cap bounds what the operator wrote. Reading them
* together is only an efficiency - one config open instead of two.
*/
/** Defaults of the session-start digest's topic and pinned lanes (task 4.2). */
export const TOPIC_HEADS_MAX_DEFAULT = 12;
export const TOPIC_HEADS_MAX_CHARS_DEFAULT = 1600;
export const PINNED_MAX_CHARS_DEFAULT = 1200;
export interface InjectionLimits {
readonly injectBudgetChars: number;
readonly standingRulesMaxChars: number;
readonly scopedRulesMaxChars: number;
/** Most topic heads the session start digest shows (task 4.2). */
readonly topicHeadsMax: number;
/** Characters for the whole topic heads block. */
readonly topicHeadsMaxChars: number;
/** Characters for the pinned context block. */
readonly pinnedMaxChars: number;
}
/**
* Resolve both ceilings, falling back to their documented defaults when
* `_brain.yaml` cannot be read.
*
* Both `_brain.yaml` failures - ABSENT and PRESENT BUT UNREADABLE -
* resolve to the defaults here, and the unreadable one is not silent for
* it: the runtime-notice channel runs inside the assembly below and puts
* `brain_config_unreadable` immediately after the standing-rules block
* and ahead of every budgeted body, naming the file and the parse
* failure. It no longer heads the payload - the operator's own rules do -
* but it still precedes everything these ceilings are applied to, which
* is the property the argument rests on. The split the `load*ConfigSafe`
* readers make is already made on this surface; making it a second time
* here would be a second channel saying the same thing.
*
* Raising instead would report less, not more. A throw on this line
* would escape the hook entirely and emit nothing at all, so the
* condition would go from stated to invisible.
*
* The one quiet path left is `OPEN_SECOND_BRAIN_RUNTIME_NOTICES=false`,
* which is the operator switching the channel off by name.
*/
export function resolveInjectionLimits(vault: string): InjectionLimits {
let cfg: BrainConfig | null = null;
try {
cfg = loadBrainConfig(vault);
} catch {
// absorbed deliberately - see the note above
}
return {
injectBudgetChars: cfg?.active?.inject_budget_chars ?? INJECT_BUDGET_CHARS_DEFAULT,
standingRulesMaxChars: resolveStandingRulesMaxChars(cfg),
scopedRulesMaxChars: resolveScopedRulesMaxChars(cfg),
topicHeadsMax: cfg?.active?.topic_heads_max ?? TOPIC_HEADS_MAX_DEFAULT,
topicHeadsMaxChars: cfg?.active?.topic_heads_max_chars ?? TOPIC_HEADS_MAX_CHARS_DEFAULT,
pinnedMaxChars: cfg?.active?.pinned_max_chars ?? PINNED_MAX_CHARS_DEFAULT,
};
}
/**
* The cap over the scoped block's sections: the configured cap, clamped
* to what the injection budget leaves once the block's header and the
* room for its notices are reserved, floor 0. With it the whole block -
* not only its sections - fits the budget it is charged against.
*/
export function scopedSectionCap(limits: InjectionLimits): number {
return Math.max(
0,
Math.min(
limits.scopedRulesMaxChars,
limits.injectBudgetChars - SCOPED_RULES_HEADER.length - SCOPED_RULES_NOTICE_RESERVE,
),
);
}
/**
* Render the scoped operator rules for this session's project and this
* device, or "" when none applies.
*
* Project and host only: a harness file renders on the MCP surfaces,
* where the harness comes from the packaged `--harness`. Both injection
* lanes are shared by Claude Code and Codex through one `o2b-hook` shim
* and have no harness signal of their own, so the harness resolves to
* nothing and matches no harness file.
*
* Never throws: a failure to resolve the scope or read the directory
* must not take the constitution and the memory context down with it.
*/
export function renderScopedBlock(
vault: string,
workspaceDir: string,
maxChars: number,
meter: InjectionMeter,
): string {
let block: string;
try {
let host: { readonly host: string | null; readonly unreadable: boolean };
try {
host = resolveHostScope(undefined);
} catch {
host = { host: null, unreadable: true };
}
block = readScopedRules(
vault,
{ project: resolveProjectScope(workspaceDir, vault), harness: null, host: host.host },
{ maxChars, hostUnreadable: host.unreadable },
).text;
} catch {
return "";
}
if (block.length === 0) return "";
meter.sources.push({
name: SOURCE_SCOPED_RULES,
text: block,
lane: LANE_BUDGETED,
outsideBoundary: true,
});
meter.scopedRulesChars = block.length;
// A budgeted source was measured under the configured ceiling, so the
// receipt carries the budget block even when no memory body follows.
meter.budgetChars = meter.configuredBudgetChars;
return block;
}
/**
* Assemble the injected context body. Returns an empty string when there is
* legitimately nothing to inject (no active.md, empty body); throws on a
* genuine read error so the fail-open loader degrades to the last-good cache.
*
* Every non-empty sub-body is recorded into `meter` as it is produced -
* the join below is where per-source attribution stops existing.
*/
export function assembleActiveContext(
vault: string,
budget: number,
meter: InjectionMeter,
): string {
// Runtime-state notices ride the same injection surface as active.md so the
// agent is proactively aware of a degraded/transient condition (semantic
// search fell back to lexical, index missing/rebuilding, read-only vault)
// without a diagnostic round-trip. Best-effort and computed with no network;
// an empty list keeps the injected body byte-identical to before.
const noticesBlock = renderRuntimeNotices(collectRuntimeNotices(vault));
if (noticesBlock.length > 0) {
meter.sources.push({
name: SOURCE_RUNTIME_NOTICES,
text: noticesBlock,
lane: LANE_UNBUDGETED,
outsideBoundary: false,
});
}
// `Brain/active.md` on an unswitched machine; on a store-only one the
// digest rendered on demand into the device-local cache (D14 item 7).
const activePath = activeDigestPathForRead(vault);
const activeBody = existsSync(activePath) ? readActiveBody(vault, activePath, budget, meter) : "";
return joinBlocks([noticesBlock, activeBody]);
}
/**
* Read + budget the active.md / lessons.md body. Returns an empty string when
* the body is empty; throws on a genuine read error (permissions, fs stall) so
* the fail-open loader degrades to the last-good cache.
*/
function readActiveBody(
vault: string,
activePath: string,
budget: number,
meter: InjectionMeter,
): string {
const body = readFileSync(activePath, "utf8");
// Drop the `kind: brain-active / generated_at` frontmatter - it
// carries no signal for the agent, only provenance for tooling.
const [, fmBody] = parseFrontmatterText(body);
const trimmed = fmBody.trim();
if (trimmed.length === 0) return "";
// A budget that cannot hold even the framing header skips the source
// whole: emitting the header alone would push the framed remainder
// past the very budget it is charged against, and metering it would
// name bytes that never reached the payload. The floor is `<=` - at
// exactly the overhead the inner budget is 0 and the budgeter answers
// with the truncation notice alone, which is over budget framed. The
// lessons reader applies the same floor to its own header.
const overhead = framingOverhead(SOURCE_ACTIVE_BODY);
if (budget <= overhead) return "";
// Injection budget (token-diet): a large preference set must not flood
// the session preamble. Resolved once in `resolveInjectionLimits`,
// which also carries the reasoning for why a config failure lands on
// the default here rather than raising. Recorded on the meter only at
// this point, because a vault with no `active.md` charged nothing
// against it and a receipt naming a budget nothing was measured under
// would be a number with no measurement behind it. The CONFIGURED
// ceiling is recorded, not the `budget` argument: that is what is left
// after the scoped rules were charged, and the receipt reports the two
// separately (`inject_budget_chars`, `scoped_rules_chars`).
// Auto-load the lessons digest alongside active.md so the agent gets
// the unified, signed, recency-scored corpus (preferences + dead-ends)
// on the same SessionStart surface. Fail-soft and budgeted separately:
// a missing / unreadable / oversized lessons file must never disturb
// the active-preferences injection above.
const lessonsBody = readLessonsBody(vault, budget);
// Untrusted vault content: neutralize (control/bidi/zero-width strip,
// delimiter escape) BEFORE budgeting, and set under the light
// framing header. The header's overhead comes out of this body's budget
// first, so the tier ladder works on the room that is actually left and
// the framed whole stays within the budget it is charged against.
const innerBudget = budget - overhead;
const inner = budgetActiveBody(neutralizeUntrustedText(trimmed), innerBudget);
// A budgeted body that is ONLY the truncation notice carries no
// content at all: framed, header + notice would land over the budget
// the source is charged against, so the ACTIVE source skips with it -
// the same honesty the sub-header floor practices, one rung up. The
// skip is this source's alone: the lessons body read above answers to
// its own header's overhead and its own budgeted remainder, so what
// it produced still emits and meters. "" is for a run where no block
// was produced at all.
const activeBlock = isTruncationNoticeOnly(inner)
? ""
: frameMemoryBody(SOURCE_ACTIVE_BODY, inner);
if (activeBlock.length > 0) {
meter.sources.push({
name: SOURCE_ACTIVE_BODY,
text: activeBlock,
lane: LANE_BUDGETED,
outsideBoundary: false,
});
}
if (lessonsBody !== null) {
meter.sources.push({
name: SOURCE_LESSONS_BODY,
text: lessonsBody,
lane: LANE_BUDGETED,
outsideBoundary: false,
});
}
// A budgeted source was measured under the configured ceiling, so the
// receipt carries the budget block whenever any memory body emitted -
// a lessons-only assembly measured itself against the same number.
if (activeBlock.length > 0 || lessonsBody !== null) {
meter.budgetChars = meter.configuredBudgetChars;
}
return joinBlocks([activeBlock, lessonsBody ?? ""]);
}
/**
* Read and budget the `Brain/lessons.md` body for injection. Returns
* `null` on any failure mode (missing file, unreadable, empty body) so
* the caller falls back to injecting active.md alone. The body is
* neutralized and framed like the active body, with the same
* budget-charged header overhead.
*/
function readLessonsBody(vault: string, budget: number): string | null {
try {
// Rendered on demand on a store-only machine; a failure is the same
// fail-soft skip as an unreadable file.
const lessonsPath = lessonsDigestPathForRead(vault);
if (!existsSync(lessonsPath)) return null;
const raw = readFileSync(lessonsPath, "utf8");
const [, body] = parseFrontmatterText(raw);
const trimmed = body.trim();
if (trimmed.length === 0) return null;
// The active body's floor, applied to this header: a body whose
// framing cannot fit - or whose budgeted remainder would be nothing
// but the truncation notice - is skipped rather than emitted over
// budget. The floor is `<=` for the same reason: at exactly the
// overhead the inner budget is 0 and the budgeter answers with the
// notice alone.
const overhead = framingOverhead(SOURCE_LESSONS_BODY);
if (budget <= overhead) return null;
const inner = budgetActiveBody(neutralizeUntrustedText(trimmed), budget - overhead);
if (isTruncationNoticeOnly(inner)) return null;
return frameMemoryBody(SOURCE_LESSONS_BODY, inner);
} catch {
return null;
}
}