Skip to content

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
3.8 KB
Raw Blame
/**
 * Server-supplied instructions returned in `initialize.instructions`.
 *
 * Two independent facts assemble here and nowhere else: WHO this agent
 * is on this vault, and WHAT this runtime actually left callable. The
 * identity line answers the first and refuses in its own way when the
 * config cannot be read; `instruction-segments.ts` answers the second
 * and renders the body from the live capability report.
 *
 * The Brain observing-memory layer is the canonical writable surface:
 * four writer tools (`brain_feedback`, `brain_apply_evidence`,
 * `brain_note`, `brain_pinned_context`) plus the read-only
 * `brain_context` reader live on the always-loaded writer scope; the
 * remaining `brain_*` surface ships on the deferred full server.
 */

import { PARAGRAPH_BREAK, renderScopeBody } from "./instruction-segments.ts";
import { TOOL_SCOPE, type ToolCapabilityReport, type ToolScope } from "./tool-contract.ts";

export interface BuildInstructionsOpts {
  /**
   * Resolved agent identity (e.g. "hermes-vps-agent"), or the error
   * explaining why it could not be resolved.
   *
   * The error form exists because the identity comes from the plugin
   * config, and a config that is present but unreadable has no identity in
   * it to state. Substituting one would be the worst available answer: the
   * instructions tell the agent to always log under the name they carry,
   * so a guessed name is a standing instruction to write under it. The
   * refusal is rendered in its place instead, naming the file.
   */
  readonly agent: string | Error;
  /** Which surface's body follows the identity line. Defaults to full. */
  readonly scope?: ToolScope;
  /**
   * What this runtime left callable, as the server's own evaluator
   * computed it.
   *
   * Required rather than optional: a default of "assume everything is
   * available" is exactly the wrong answer this parameter exists to
   * remove, and it would be indistinguishable at the call site from a
   * runtime that really does have everything. The server holds the
   * report on the instance from construction, so there is no caller that
   * would have to invent one.
   */
  readonly capabilities: ToolCapabilityReport;
}

/**
 * The opening identity sentence of every scope's instructions.
 *
 * Both branches are an instruction, not a report: the resolved branch says
 * which name to log under, and the unresolved branch says that there is
 * none and that the writers will refuse until the named file is fixed - so
 * an agent reading it does not go looking for a name to supply by hand.
 * The error carries its own remedy (`ConfigReadError` renders the chmod),
 * so nothing is assembled here.
 */
function identityLine(agent: string | Error): string {
  if (typeof agent === "string") {
    return (
      `You are @${agent} on this Open Second Brain vault. ` +
      "Always log under this identity; do not invent or change the name."
    );
  }
  return (
    "Your identity on this Open Second Brain vault is UNRESOLVED: " +
    `${agent.message} Until it is readable, every tool that writes under an ` +
    "identity refuses and names that file; do not substitute a name of your " +
    "own. The read-only diagnostics (vault_health, second_brain_status) " +
    "still answer and report the same condition."
  );
}

/**
 * Build the `initialize.instructions` block for one server process.
 *
 * Every scope opens with the identity line. The writer scope is the
 * always-loaded surface and its four writers are exactly the
 * identity-bearing ones, so the surface where the name matters most was
 * the one that used to omit it; the catalog scope hydrates into the same
 * writers.
 */
export function buildInstructions(opts: BuildInstructionsOpts): string {
  const scope = opts.scope ?? TOOL_SCOPE.full;
  return identityLine(opts.agent) + PARAGRAPH_BREAK + renderScopeBody(scope, opts.capabilities);
}