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 scope bodies of `initialize.instructions`, as tool-tagged segments.
*
* ## Why the text is not a constant any more
*
* The instruction block is the first thing every agent reads, and it used
* to be one frozen string per scope. This server already evaluates a
* runtime capability window and knows, per tool, whether it is available
* or withheld and why (`evaluateToolCapabilities`) - so a host that
* disables `brain_note` produced a handshake whose opening paragraph
* instructed the agent to call it. The agent then calls, reads the
* refusal, and learns that the first text it was given was wrong.
*
* Appending a "…except these" block beneath the same prose does not fix
* that. An instruction and its retraction in one document leave the
* reader deciding which half is true, and the half printed first is the
* one that shapes the plan. So the guidance is REMOVED, and the removal
* is NAMED with the reason the evaluator already produced. No second
* vocabulary is invented here: every reason in the withheld block is a
* string {@link evaluateToolCapabilities} wrote.
*
* ## The model
*
* A scope body is an ordered list of {@link InstructionParagraph}s
* joined by a blank line. A paragraph is an ordered list of
* {@link InstructionSegment}s, each declaring the tool names its text
* instructs the reader to call.
*
* - A segment renders when EVERY tool it names is available. A segment
* naming none is unconditional text.
* - Between two rendered segments goes the `separator` of the earlier
* one, so a dropped clause takes its own punctuation with it and the
* survivors still read as one sentence.
* - A paragraph whose every tool-bearing segment was dropped renders
* NOTHING, its unconditional text included. A lead-in with nothing
* left to lead into is not guidance, and a sentence such as "Five
* tools live here" is a claim that stops being true the moment one
* of them is withheld.
* - The exception to that last rule is declared, not inferred: a
* segment marked {@link InstructionSegment.standsAlone} states a
* fact of its own rather than introducing the items around it, so it
* keeps its paragraph alive when they go.
*
* A paragraph's LEAD-IN is a segment, not a prefix welded to the first
* item. It has to be, or withholding the first tool takes the heading
* with it and the survivors open mid-sentence - the memory contract
* losing "Memory contract: call", the view list losing "Consolidated
* read views:".
*
* The fully-available render is byte-identical to the strings this model
* replaces; `tests/mcp/instruction-segments.test.ts` pins that against a
* captured fixture so a reshaping cannot quietly become a rewrite.
*
* The catalog body carries the one deliberate exception. Its frozen
* string said every tool omitted from `tools/list` stays callable
* through `tools/call`; that is true of the catalog surface's hiding
* and false of a capability window, which removes the tool from the
* table `tools/call` routes on. Carrying that sentence unchanged into a
* module whose whole subject is the window would ship a handshake that
* contradicts the runtime it was rendered for, so the sentence now
* separates the two cases and the fixture carries the corrected text.
*
* ## What the withheld block does and does not list
*
* It lists the tools THIS TEXT would have instructed and cannot - the
* intersection of the report's `withheld` entries with the names the
* scope's segments declare. Not the whole withheld set: a `max_tools`
* window on the full scope withholds over a hundred tools, and pasting
* that list into the handshake would spend more tokens explaining an
* absence than the removed guidance ever cost.
*
* The block closes by saying where the complete report is - but only on
* a surface that has one. No capability WINDOW ever withholds
* {@link CAPABILITY_DIAGNOSTIC_TOOL}, and the writer scope does not
* register it at all: `buildToolTable("writer")` is the five always-
* loaded tools and nothing else. Pointing an agent there would be the
* defect this module exists to remove, reintroduced by the sentence
* that explains the removal, so the pointer is emitted only when the
* report says the tool is available and the names stand alone
* otherwise.
*/
import { CAPABILITY_DIAGNOSTIC_TOOL } from "./capabilities.ts";
import { TOOL_SCOPE, type ToolCapabilityReport, type ToolScope } from "./tool-contract.ts";
/** One run of instruction text and the tools whose availability it assumes. */
export interface InstructionSegment {
/**
* Tool names the text instructs the reader to call. Empty means the
* text stands whatever the runtime withholds.
*/
readonly tools: ReadonlyArray<string>;
/** The text, carrying no leading or trailing separator of its own. */
readonly text: string;
/**
* Placed before the next rendered segment of the same paragraph.
* Absent on the last segment, and on any segment whose successor
* begins a new sentence of its own.
*/
readonly separator?: string;
/**
* Exempts this segment from the paragraph-drop rule.
*
* Unconditional text is a lead-in by default, and a lead-in goes when
* its items go. A segment that states a fact of its own does not:
* what the catalog surface's hiding does and does not do to
* callability is true whatever the runtime withholds, and it is the
* sentence the catalog's "Second pass" depends on to mean anything.
*/
readonly standsAlone?: boolean;
}
/** Segments that render as one paragraph. */
export interface InstructionParagraph {
readonly segments: ReadonlyArray<InstructionSegment>;
/** Appended once after the last rendered segment, when any rendered. */
readonly end?: string;
}
/**
* Between two paragraphs, and between the body and the withheld block.
*
* Exported because the identity line is joined to the body with this
* same break one module up: two spellings of one document's block
* separator can drift, and the fixture that would catch the drift is
* pinned against the joined result.
*/
export const PARAGRAPH_BREAK = "\n\n";
/** Between the lines of a bulleted paragraph. */
const LINE_BREAK = "\n";
/** Between two clauses of one sentence. */
const CLAUSE = "; ";
/** Between two sentences of one paragraph. */
const SENTENCE = ". ";
/** Between two items of an inline list. */
const ITEM = ", ";
/** Between a lead-in and the first item it introduces. */
const LEAD_IN = " ";
/** Indent of a bullet, matching the shipped writer body. */
const BULLET = " - ";
/** Heading of the block that names what this runtime withheld. */
export const WITHHELD_BLOCK_HEADING =
"Withheld in this runtime, so the guidance naming them is not in the text above:";
/** Closing line of the withheld block: where the complete report is. */
const WITHHELD_BLOCK_POINTER =
`Call ${CAPABILITY_DIAGNOSTIC_TOOL} for the complete availability report; ` +
"it lists tools this text never names.";
/**
* Reason a segment's tool carries when the report knows nothing about it.
*
* Unreachable in a shipped build - the orphan census in
* `tests/mcp/instruction-segments.test.ts` fails on a segment naming a
* tool its scope does not register - and stated anyway, because the
* alternative is a segment that disappears with no line saying so.
*/
const UNREGISTERED_REASON = "not registered in this server's tool table";
/** The always-loaded writer surface, in the order the writer body lists it. */
const WRITER_TOOLS = Object.freeze([
"brain_feedback",
"brain_apply_evidence",
"brain_note",
"brain_pinned_context",
"brain_context",
]);
/** The deferred catalog's own entry point. */
const HYDRATE_TOOL = "tool_hydrate";
/** The consolidated read views the full body advertises. */
const VIEW_TOOLS = Object.freeze(["brain_brief", "brain_analytics", "schema_inspect"]);
/** The escape hatch for a truncated preview. */
const ARTIFACT_TOOL = "brain_artifact_get";
/** Text that stands whatever the runtime withholds. */
function unconditional(text: string, separator?: string): InstructionSegment {
return { tools: [], text, ...(separator === undefined ? {} : { separator }) };
}
const FULL_BODY: ReadonlyArray<InstructionParagraph> = Object.freeze([
{
end: ".",
segments: [
unconditional("Memory contract: call", LEAD_IN),
{
tools: ["brain_feedback"],
text: "brain_feedback once per taste signal the user expresses",
separator: CLAUSE,
},
{
tools: ["brain_apply_evidence"],
text:
"brain_apply_evidence right after producing a durable artifact an active " +
"preference scopes to (result: applied | violated | outdated)",
separator: CLAUSE,
},
{
tools: ["brain_note"],
text: "brain_note for narrative milestones that fit neither",
separator: CLAUSE,
},
{
tools: ["brain_pinned_context"],
text: "brain_pinned_context for current-task facts that must survive context rotation",
separator: SENTENCE,
},
{
tools: ["brain_context"],
text: "brain_context bootstraps a session when the host injects no active-preferences hook",
separator: SENTENCE,
},
unconditional(
"Skip Brain calls for casual chat, exploration, and trivial edits - " +
"a misrecorded signal is worse than a missed one",
),
],
},
{
end: ".",
segments: [
unconditional("Consolidated read views:", LEAD_IN),
{
tools: ["brain_brief"],
text: "brain_brief (view: morning | daily | weekly | monthly | operator | digest)",
separator: ITEM,
},
{
tools: ["brain_analytics"],
text:
"brain_analytics (view: timeline | attention_flows | belief_evolution | " +
"concept_synthesis)",
separator: ITEM,
},
{
tools: ["schema_inspect"],
text:
"schema_inspect (view: graph | lint | stats | orphans | explain_type | " +
"active_pack | packs)",
separator: SENTENCE,
},
{
// The sentence is about the aliases of those three views, so it
// stands or falls with them rather than dangling on its own.
tools: VIEW_TOOLS,
text: "The per-view predecessor names still resolve via tools/call as deprecated aliases",
},
],
},
{
segments: [
{
tools: [ARTIFACT_TOOL],
text:
"Preview budget: a large result may arrive as a JSON envelope with " +
"`preview_truncated: true` and an `artifact_id`; fetch the full payload " +
"with brain_artifact_get only when the preview is not enough.",
},
],
},
]);
const WRITER_BODY: ReadonlyArray<InstructionParagraph> = Object.freeze([
{ segments: [unconditional("Open Second Brain — always-loaded MCP surface.")] },
{
segments: [
{
// The count is a claim about the whole set, so it goes when any
// member does; the bullets that survive still say what is here.
tools: WRITER_TOOLS,
text:
"Five tools live here (four writers + one reader; the server's name is\n" +
"preserved for backward compatibility with existing client configs):",
separator: LINE_BREAK,
},
{
tools: ["brain_feedback"],
text: `${BULLET}brain_feedback — record one new taste signal the user just expressed.`,
separator: LINE_BREAK,
},
{
tools: ["brain_apply_evidence"],
text:
`${BULLET}brain_apply_evidence — record applied | violated | outdated against an\n` +
" active preference for an artifact this turn produced.",
separator: LINE_BREAK,
},
{
tools: ["brain_note"],
text:
`${BULLET}brain_note — record one narrative milestone (release shipped,\n` +
" PR merged, fact discovered) that fits neither\n" +
" category.",
separator: LINE_BREAK,
},
{
tools: ["brain_pinned_context"],
text:
`${BULLET}brain_pinned_context — read/write/append/clear the pinned context for\n` +
" current-task facts that should survive context\n" +
" rotation without becoming permanent preferences.",
separator: LINE_BREAK,
},
{
tools: ["brain_context"],
text:
`${BULLET}brain_context — pull the active-preferences digest plus\n` +
" pinned context and active-preference counts.\n" +
" Read-only. Use at session\n" +
" start when the host runtime lacks a SessionStart\n" +
" hook (Cursor, Aider, raw Claude API). Runtimes that\n" +
" already inject the digest via a hook can skip this.",
},
],
},
{
segments: [
unconditional(
'The remaining Brain surface lives on the sibling "open-second-brain"\n' +
"MCP server (deferred), including additional read-only, analytics,\n" +
"maintenance, and workflow tools beyond the always-loaded writer set.\n" +
"Use ToolSearch to discover and reach it.",
),
],
},
{
segments: [
{
tools: WRITER_TOOLS.filter((name) => name !== "brain_context"),
text:
"Prefer the writer-server copies of brain_feedback / brain_apply_evidence /\n" +
"brain_note / brain_pinned_context over any duplicate exposed by the full server — both call the same\n" +
"handler, but the writer copy is always available without ToolSearch.",
},
],
},
]);
const CATALOG_BODY: ReadonlyArray<InstructionParagraph> = Object.freeze([
{ segments: [unconditional("Open Second Brain — two-pass catalog MCP surface.")] },
{
segments: [
{
// The enumeration is a claim about a set, so it goes when a
// member does.
tools: [...WRITER_TOOLS, HYDRATE_TOOL],
text:
"This server advertises a compact first-pass tool set: the capability\n" +
"diagnostic, the five always-loaded Brain writers/readers, and\n" +
"tool_hydrate",
separator: SENTENCE,
},
{
// The fact that nothing is unreachable does not depend on which
// tools this runtime allows, and the "Second pass" paragraph
// below is unreadable without it.
tools: [],
standsAlone: true,
text:
"A tool the catalog surface alone omits from\n" +
"tools/list stays CALLABLE via tools/call — the omission keeps schema\n" +
"tokens out of your prompt until needed. A tool a runtime capability\n" +
"window withholds is not callable at all.",
},
],
},
{
segments: [
{
tools: [HYDRATE_TOOL],
text:
"Second pass: call tool_hydrate with no arguments to get the compact\n" +
"catalog (name, one-line description, group) of every tool in this\n" +
"process, then call tool_hydrate with names: [...] to fetch the full\n" +
"input/output schemas for the tools you actually need. After hydration,\n" +
"invoke those tools directly by name through tools/call — no further\n" +
"registration step exists or is needed.",
},
],
},
{
segments: [
{
tools: [HYDRATE_TOOL],
text:
"Do not invent substitute workflows for a capability you cannot see:\n" +
"hydrate the catalog first; the tool is almost certainly already here.",
},
],
},
]);
/**
* The body of each scope.
*
* A total map rather than a chain of `if`s: a scope added to
* {@link TOOL_SCOPE} without a body here fails to compile.
*/
const SCOPE_BODIES: Readonly<Record<ToolScope, ReadonlyArray<InstructionParagraph>>> =
Object.freeze({
[TOOL_SCOPE.full]: FULL_BODY,
[TOOL_SCOPE.writer]: WRITER_BODY,
[TOOL_SCOPE.catalog]: CATALOG_BODY,
});
/** Every tool name the segments of `scope` declare, in declaration order. */
export function segmentToolNames(scope: ToolScope): string[] {
const seen = new Set<string>();
for (const paragraph of SCOPE_BODIES[scope]) {
for (const segment of paragraph.segments) {
for (const name of segment.tools) seen.add(name);
}
}
return [...seen];
}
/** One paragraph, or null when nothing in it survived the runtime. */
function renderParagraph(
paragraph: InstructionParagraph,
isAvailable: (name: string) => boolean,
): string | null {
const rendered = paragraph.segments.filter((segment) => segment.tools.every(isAvailable));
if (rendered.length === 0) return null;
const conditional = paragraph.segments.some((segment) => segment.tools.length > 0);
const survivesOnItsOwn = rendered.some(
(segment) => segment.tools.length > 0 || segment.standsAlone === true,
);
if (conditional && !survivesOnItsOwn) return null;
let out = "";
let pending = "";
for (const segment of rendered) {
out += pending + segment.text;
pending = segment.separator ?? "";
}
return out + (paragraph.end ?? "");
}
/** The withheld block, or null when this scope's guidance survived intact. */
function renderWithheldBlock(scope: ToolScope, report: ToolCapabilityReport): string | null {
const reasons = new Map(report.withheld.map((entry) => [entry.name, entry.reason]));
const available = new Set(report.available.map((entry) => entry.name));
const lines: string[] = [];
for (const name of segmentToolNames(scope)) {
if (available.has(name)) continue;
lines.push(`${BULLET}${name}: ${reasons.get(name) ?? UNREGISTERED_REASON}`);
}
if (lines.length === 0) return null;
if (!available.has(CAPABILITY_DIAGNOSTIC_TOOL)) {
return [WITHHELD_BLOCK_HEADING, ...lines].join(LINE_BREAK);
}
return [WITHHELD_BLOCK_HEADING, ...lines, "", WITHHELD_BLOCK_POINTER].join(LINE_BREAK);
}
/**
* The instruction body for `scope` under the runtime `report` describes.
*
* The identity line is not part of it: that is the caller's, because it
* answers a different question and refuses for a different reason.
*
* Both arguments carry the scope, and a mismatch is refused BY NAME
* rather than rendered. The evaluator's `available` set is what decides
* every segment here, so a report built for another scope deletes every
* paragraph and then explains the deletion with reasons that are not
* true of this server - a confident wrong answer where the caller
* passed two arguments that disagree.
*/
export function renderScopeBody(scope: ToolScope, report: ToolCapabilityReport): string {
if (report.scope !== scope) {
throw new Error(
`capability report is for the ${report.scope} scope, not ${scope}: ` +
"the instruction body and the availability it renders must describe one server",
);
}
const available = new Set(report.available.map((entry) => entry.name));
const isAvailable = (name: string): boolean => available.has(name);
const blocks: string[] = [];
for (const paragraph of SCOPE_BODIES[scope]) {
const text = renderParagraph(paragraph, isAvailable);
if (text !== null) blocks.push(text);
}
const withheld = renderWithheldBlock(scope, report);
if (withheld !== null) blocks.push(withheld);
return blocks.join(PARAGRAPH_BREAK);
}