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
/**
* Injection budget for the rendered `Brain/active.md` body
* (token-diet, t_40eb1de7 part 2).
*
* The SessionStart hook injects the file verbatim; on a vault with a
* large preference set that preamble grows without bound. This module
* fits the body into a character budget through the shared
* section-aware truncation core, in a deterministic ladder:
*
* 1. HEADLINE TIER - on an over-budget body, sections below the
* keep-guard priority holding more bullets than
* {@link HEADLINE_TIER_TOP_ITEMS} are compacted to their heading,
* their non-bullet lead-ins and the top-N ranked bullets, ranked by
* the inline tags. Compaction runs SEQUENTIALLY in the drop order,
* least important section first, stopping as soon as the body fits
* - a small overflow costs the least valuable section a few
* bullets instead of stripping every non-guard section at once.
* 2. Whole-section drops, in fixed priority order - recently retired
* first, then quarantine, then most-applied, with the confirmed
* rules (and the document preamble) surviving longest.
* 3. A one-line notice names what happened: the sections that went,
* the headlines kept when tiering fired, how many characters
* survived out of how many, and the pointer to `brain_context`
* for the full view. When tiering alone brought the body within
* budget, the tier notice rides alone - a reduction is never
* silent.
*
* Pure and deterministic; the hook stays a thin IO shell.
*/
import {
applySectionBudget,
type BudgetSection,
joinSections,
joinedSectionsLength,
type SectionTruncationReport,
SECTION_SEPARATOR,
splitSectionBullets,
topItemLines,
} from "./text/text-budget.ts";
/**
* Separator between a section's ordinal and its heading inside a budget
* key. The ordinal keeps keys unique when a vault renders two sections
* with the same heading; the notice strips it back off, so the two sides
* share the character rather than each spelling it.
*/
const SECTION_KEY_SEPARATOR = ":";
/** The Markdown level every active.md section heading is rendered at. */
const HEADING_PREFIX = "## ";
/** Key of the slice holding everything before the first heading. */
const PREAMBLE_KEY = "preamble";
/**
* The shared tail of every truncation notice: the pointer from the
* budgeted view back to the full preference set. Spelled out once so
* the drop notice and the tier notice can never drift apart.
*/
const FULL_VIEW_POINTER =
" Call `brain_context` (or run `o2b brain export --format llms-txt`) for the full preference set._";
/**
* The truncation notice, built from the budgeter's own report.
*
* It used to be a fixed sentence. The budgeter has always returned the
* list of keys it dropped, and the caller has always discarded it, so an
* agent whose quarantine rules had just been evicted was told only that
* "the injection was truncated" - the exact silence this release exists
* to close. Naming the sections is safe because they are headings THIS
* project renders, never operator or user text: no content crosses into
* the notice, only keys and two integers.
*/
export function activeTruncationNotice(
report: SectionTruncationReport,
tieredLinesCut = 0,
): string {
const dropped =
report.droppedKeys.length > 0
? ` Dropped ${report.droppedKeys.length} ` +
`section${report.droppedKeys.length === 1 ? "" : "s"} ` +
`(${report.droppedKeys.map(sectionLabel).join(", ")})` +
(tieredLinesCut > 0
? `; ${tieredLinesCut} rule ${tieredLinesCut === 1 ? "line" : "lines"} cut.`
: ".")
: "";
return (
`${TRUNCATION_NOTICE_OPEN} kept ${report.keptChars} of ${report.totalChars} ` +
`characters.${dropped}${FULL_VIEW_POINTER}`
);
}
/**
* The opening words of the drop notice `activeTruncationNotice` renders,
* spelled once so the notice and the notice-only test below can never
* drift apart - a copy of the wording elsewhere would silently disable
* the test the moment the sentence changed.
*/
const TRUNCATION_NOTICE_OPEN = "_Injection truncated to budget:";
/**
* True when a BUDGETED body is nothing but the drop notice: every
* section was dropped whole and no content survived. The notice is
* always a body's TAIL (surviving content first, notice appended after
* a separator), so a body OPENING with the notice can only be the
* notice alone - or vault prose contrived to open with the notice's
* sentence AND overflow, which fails safe the same way (less injected,
* never over budget). Exported for the injection assembler, which skips
* such a body instead of framing a multi-hundred-character notice over
* the very budget the source is charged against.
*/
export function isTruncationNoticeOnly(body: string): boolean {
return body.startsWith(TRUNCATION_NOTICE_OPEN);
}
/**
* Human-readable name of a dropped section: the ordinal prefix and the
* Markdown heading marker removed, leaving the heading as the operator
* reads it in `Brain/active.md`.
*/
function sectionLabel(key: string): string {
const at = key.indexOf(SECTION_KEY_SEPARATOR);
const heading = at === -1 ? key : key.slice(at + SECTION_KEY_SEPARATOR.length);
return heading.startsWith(HEADING_PREFIX) ? heading.slice(HEADING_PREFIX.length) : heading;
}
/**
* Drop priority per known section heading; lower survives longer.
* The preamble (everything before the first `## `) shares priority 0
* with Confirmed. Unknown future sections sit between most-applied
* and quarantine.
*
* Exported so the proactive budget-pressure probe
* (`active-budget-pressure.ts`) ranks eviction candidates against the
* exact same drop order this reactive truncation uses - the two
* surfaces must never disagree about which section goes first.
*/
export const SECTION_PRIORITIES: ReadonlyArray<{
readonly prefix: string;
readonly priority: number;
}> = [
{ prefix: `${HEADING_PREFIX}Confirmed`, priority: 0 },
{ prefix: `${HEADING_PREFIX}Most-applied`, priority: 1 },
{ prefix: `${HEADING_PREFIX}Quarantine`, priority: 3 },
{ prefix: `${HEADING_PREFIX}Recently retired`, priority: 4 },
];
/**
* Priority shared by the preamble and any priority-0 section (Confirmed).
* A section at this priority is a live rule/config the pressure probe
* treats as a keep-guard: it is never proposed as an eviction candidate.
*/
export const KEEP_GUARD_PRIORITY = 0;
export const UNKNOWN_SECTION_PRIORITY = 2;
export function priorityFor(heading: string): number {
for (const { prefix, priority } of SECTION_PRIORITIES) {
if (heading.startsWith(prefix)) return priority;
}
return UNKNOWN_SECTION_PRIORITY;
}
/**
* Split a rendered active.md body into `## `-delimited sections,
* keeping the preamble attached to the front of the first slice.
*
* Exported for reuse by the budget-pressure probe so both surfaces
* split identically.
*/
export function splitSections(body: string): BudgetSection[] {
const lines = body.split("\n");
const sections: BudgetSection[] = [];
let currentKey = PREAMBLE_KEY;
let currentPriority = 0;
let buffer: string[] = [];
const flush = (): void => {
// Trim the trailing blank separator off each slice; the budget
// core re-joins sections with a blank line.
while (buffer.length > 0 && buffer[buffer.length - 1] === "") buffer.pop();
if (buffer.length === 0) return;
sections.push({
key: `${sections.length}${SECTION_KEY_SEPARATOR}${currentKey}`,
priority: currentPriority,
text: buffer.join("\n"),
});
buffer = [];
};
for (const line of lines) {
if (line.startsWith(HEADING_PREFIX)) {
// The preamble merges into the first heading's section so the
// document title can never be dropped ahead of its content.
if (currentKey !== PREAMBLE_KEY || priorityFor(line) !== 0) flush();
if (currentKey === PREAMBLE_KEY && priorityFor(line) === 0) {
currentKey = line;
currentPriority = 0;
buffer.push(line);
continue;
}
currentKey = line;
currentPriority = priorityFor(line);
}
buffer.push(line);
}
flush();
return sections;
}
/**
* Fit `body` into `budgetChars`. Within budget the input passes
* through byte-identical (the idempotent-write comparison upstream
* stays valid); over budget the headline tier runs first - sections
* below the keep-guard priority compacted sequentially in the drop
* order, least important first, only until the body fits - then the
* section drop order is deterministic.
*
* When tiering fired, the reduction is never silent: the tier notice
* rides alone when tiering alone brought the body within budget, and a
* "headlines kept" clause joins the drop notice otherwise. The drop
* notice's character pair quantifies the cut against the ORIGINAL
* body, not the tiered remainder the drop pass receives.
*/
export function budgetActiveBody(body: string, budgetChars: number): string {
if (body.length <= budgetChars) return body;
const sections = splitSections(body);
// The drop pass below sees the TIERED sections; the notice must
// quantify the cut against the body the vault holds, so the original
// join is captured before the ladder runs and overrides the report.
const originalTotal = joinedSectionsLength(sections);
const ladder = applyHeadlineTiers(sections, budgetChars);
const tieredLabels = ladder.tieredKeys.map(sectionLabel);
if (tieredLabels.length > 0 && joinedSectionsLength(ladder.sections) <= budgetChars) {
// Tiering alone brought the body within budget: nothing was
// dropped, but the body the consumer sees is no longer the body the
// vault holds. Say so through the tier notice, mirroring the drop
// notice's shape so a reduction is never silent. The cut-count clause
// rides only when it still fits the budget; the notice stays.
const tiered = joinSections(ladder.sections) + SECTION_SEPARATOR;
const counted = tiered + activeTierNotice(tieredLabels, ladder.linesCut);
return counted.length <= budgetChars ? counted : tiered + activeTierNotice(tieredLabels);
}
const result = applySectionBudget(ladder.sections, budgetChars, {
totalChars: originalTotal,
notice:
tieredLabels.length > 0
? (report) => {
// Survivors only: a section tiered and THEN dropped whole is
// already named in the Dropped list, and naming it in the
// kept-headlines clause too made the notice contradict
// itself. No tiered section survived - the clause stays out.
const keptTiered = ladder.tieredKeys.filter((k) => !report.droppedKeys.includes(k));
// Its count is of those survivors; the total rides the drop notice.
const keptCut = keptTiered.reduce(
(sum, k) => sum + (ladder.linesCutByKey.get(k) ?? 0),
0,
);
const clause =
keptTiered.length > 0 ? tierNoticeClause(keptTiered.map(sectionLabel), keptCut) : "";
return `${activeTruncationNotice(report, ladder.linesCut)}${clause}`;
}
: activeTruncationNotice,
});
return result.body;
}
/**
* Bullets a tiered section keeps: the headline tier between
* section-intact and section-dropped. A named constant, not a config
* key - the ladder is deterministic machinery shared with the proactive
* pressure probe, and a second tunable surface would let the two drift
* apart.
*/
export const HEADLINE_TIER_TOP_ITEMS = 3;
/**
* Wording of the notice emitted when the headline tier fired and the
* tiered body fits the budget on its own (no section dropped). Mirrors
* the drop notice's shape - what happened, then the pointer to the full
* view - so a reduction is never silent.
*/
const TIER_NOTICE_OPEN = "_Headlines kept to fit the injection budget: ";
const TIER_NOTICE_POINTER = `.${FULL_VIEW_POINTER}`;
/**
* Wording of the "headlines kept" clause appended to the drop notice
* when tiering fired AND tiered sections SURVIVED the drop pass: the
* consumer must be able to tell a tiered, partially-kept section from
* an intact one. A tiered section that then dropped whole is named in
* the Dropped list alone - the clause never names it too.
*/
const TIER_CLAUSE_OPEN = " _Headlines kept in: ";
const TIER_CLAUSE_CLOSE = "._";
/**
* The tier-alone notice: names the sections the ladder compacted, in
* render order, and points at the full view. Labels are headings this
* project renders, never operator text - the same safety the drop
* notice's naming relies on.
*/
export function activeTierNotice(tieredLabels: ReadonlyArray<string>, linesCut = 0): string {
const counted = linesCut > 0 ? `; ${linesCut} rule ${linesCut === 1 ? "line" : "lines"} cut` : "";
return `${TIER_NOTICE_OPEN}${tieredLabels.join(", ")}${counted}${TIER_NOTICE_POINTER}`;
}
function tierNoticeClause(tieredLabels: ReadonlyArray<string>, linesCut: number): string {
const counted = linesCut > 0 ? `; ${linesCut} rule ${linesCut === 1 ? "line" : "lines"} cut` : "";
return `${TIER_CLAUSE_OPEN}${tieredLabels.join(", ")}${counted}${TIER_CLAUSE_CLOSE}`;
}
/**
* One headline-tier step: compact a section below the keep-guard
* priority to its heading, its non-bullet lead-ins and the top
* `topItems` ranked bullets. Sections at or below
* {@link KEEP_GUARD_PRIORITY} (the preamble and the confirmed rules)
* are live config and are never compacted; a section already holding at
* most `topItems` bullets is returned untouched.
*
* The tiered text is a byte-prefix of the original: head lines verbatim,
* then the surviving bullets in render order. `headLines` is set to the
* kept non-bullet line count so a headlines-only remnant that still
* overflows drops whole through the budgeter's existing guard instead
* of standing there looking complete.
*
* Pure and deterministic. Exported for the pressure probe, which must
* model this exact step.
*/
export function tierSection(
section: BudgetSection,
topItems: number = HEADLINE_TIER_TOP_ITEMS,
): { section: BudgetSection; tiered: boolean; linesCut: number } {
if (section.priority <= KEEP_GUARD_PRIORITY) return { section, tiered: false, linesCut: 0 };
const split = splitSectionBullets(section.text);
if (split.itemLines.length <= topItems) return { section, tiered: false, linesCut: 0 };
const kept = topItemLines(split.itemLines, topItems);
return {
tiered: true,
linesCut: split.itemLines.length - kept.length,
section: {
...section,
headLines: split.headLines.length,
text: [...split.headLines, ...kept].join("\n"),
},
};
}
export interface HeadlineTierResult {
/** Sections after the ladder: tiered where applicable, order preserved. */
readonly sections: ReadonlyArray<BudgetSection>;
/** Keys of the sections the ladder actually compacted, in render order. */
readonly tieredKeys: ReadonlyArray<string>;
/** How many rule lines the tier cut in total, across the tiered sections. */
readonly linesCut: number;
/** How many rule lines the tier cut in each tiered section, by key. */
readonly linesCutByKey: ReadonlyMap<string, number>;
}
/**
* The headline tier ladder over a split body: when the sections fit
* `budgetChars` untouched, nothing is compacted (within-budget
* byte-identity is the caller's contract). Otherwise the ladder tiers
* SEQUENTIALLY in the drop order - least important section first
* (highest drop-priority number, ties to the later render position, the
* same selection the budget pass makes) - recomputing the joined total
* after each compaction and stopping as soon as the body fits, so a
* five-character overflow costs the low-value section a few bullets
* instead of stripping every non-guard section at once. Sections the
* tier cannot compact (keep-guard, at or below the top-N) are passed
* over; when the ladder runs out of them and the body still overflows,
* the caller hands the tiered body to the drop pass.
*
* Pure and deterministic. Exported for the pressure probe, which must
* model this exact step with the same exemptions and the same top-N.
*/
export function applyHeadlineTiers(
sections: ReadonlyArray<BudgetSection>,
budgetChars: number,
topItems: number = HEADLINE_TIER_TOP_ITEMS,
): HeadlineTierResult {
if (joinedSectionsLength(sections) <= budgetChars) {
return { sections, tieredKeys: [], linesCut: 0, linesCutByKey: new Map() };
}
const out: BudgetSection[] = [...sections];
const tieredAt = new Set<number>();
const linesCutByKey = new Map<string, number>();
let linesCut = 0;
const order = sections
.map((_, index) => index)
.toSorted((a, b) => sections[b]!.priority - sections[a]!.priority || b - a);
for (const index of order) {
const step = tierSection(out[index]!, topItems);
if (!step.tiered) continue;
out[index] = step.section;
tieredAt.add(index);
linesCut += step.linesCut;
linesCutByKey.set(sections[index]!.key, step.linesCut);
if (joinedSectionsLength(out) <= budgetChars) break;
}
// Keys in render order: the notice names the compacted sections the
// way the body renders them, whichever order the ladder visited them.
const tieredKeys = sections.filter((_, i) => tieredAt.has(i)).map((s) => s.key);
return { sections: out, tieredKeys, linesCut, linesCutByKey };
}