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
15.4 KB
Raw Blame
/**
 * The record readers of the `osb://` surface (task 3.19): one
 * preference, one topic, one log day, each answered at the caller's
 * reach, with the topic and status markdown renderers and the topic
 * objection section. Split from `resources.ts`; dispatch happens
 * through that module's `readResource`.
 */

import { storeMemoryPageAt } from "../core/brain/memory-pages.ts";
import { logDayReader } from "../core/brain/log-days.ts";
import { vaultRelative } from "../core/path-safety.ts";
import { formatFrontmatter } from "../core/vault.ts";
import { readFileSync } from "node:fs";
import { listLogMarkdownFiles } from "../core/brain/log-jsonl.ts";
import {
  preferencePath,
  retiredPath,
  validateIsoDate,
  validateSlug,
  BRAIN_PREFERENCES_REL,
} from "../core/brain/paths.ts";
import { BrainNotFoundError, queryByPreference, queryByRuleTopic } from "../core/brain/query.ts";
import { type ArtifactRefView } from "../core/brain/artifact-ref-view.ts";
import { logEntriesAtReach, recordRefs } from "../core/brain/log-events-at-reach.ts";
import {
  parseLogDayFile,
  renderLogDayHeader,
  renderLogEntryBlock,
  type ParseLogDayResult,
} from "../core/brain/log.ts";
import type { BrainPreference, BrainRetired } from "../core/brain/types.ts";
import { deliveryRelForBrainArtifact, signalDeliveryRel } from "./brain/reach-events.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";
import type { RequestView, ResourceContent, ResourceContext } from "./resources-shared.ts";
import { MIME_MARKDOWN, deliveryFor, notFound, readMarkdown } from "./resources-shared.ts";

export function readPreference(
  ctx: ResourceContext,
  uri: string,
  rawId: string,
  view: RequestView,
): ResourceContent {
  if (!rawId.trim()) {
    throw new MCPError(INVALID_PARAMS, `resource id must not be empty: ${uri}`);
  }
  // Accept `pref-foo`, `ret-foo`, or the bare slug. Strip the prefix
  // (if any) for `validateSlug` — that helper rejects `..` traversal
  // and other shape problems with a clear INVALID_PARAMS-shaped
  // message, which is a better diagnosis than a downstream
  // "not found" error. The prefixed form is then handed to
  // queryByPreference, which handles the active → retired fallback.
  const slug = rawId.startsWith("pref-")
    ? rawId.slice("pref-".length)
    : rawId.startsWith("ret-")
      ? rawId.slice("ret-".length)
      : rawId;
  try {
    validateSlug(slug);
  } catch (err) {
    throw new MCPError(INVALID_PARAMS, (err as Error).message);
  }
  const normalized =
    rawId.startsWith("pref-") || rawId.startsWith("ret-") ? rawId : `pref-${rawId}`;
  // Asked before the page is parsed: a withheld page that fails to parse
  // would otherwise answer with the parser's error, which names the page
  // an absent id never could.
  if (!view.refs.row(...recordRefs(normalized))) throw notFound(normalized);
  let result;
  try {
    result = queryByPreference(ctx.vault, normalized);
  } catch (err) {
    if (err instanceof BrainNotFoundError) {
      throw new MCPError(INTERNAL_ERROR, err.message);
    }
    throw err;
  }
  // queryByPreference returns the parsed object but not its path; we
  // re-derive the path from the resolved id so we can hand back the
  // raw markdown body (the resource contract is "give me the file",
  // not "give me a structured projection").
  const resolvedId = result.preference.id;
  const resolvedSlug = resolvedId.startsWith("pref-")
    ? resolvedId.slice("pref-".length)
    : resolvedId.slice("ret-".length);
  const filePath = resolvedId.startsWith("pref-")
    ? preferencePath(ctx.vault, resolvedSlug)
    : retiredPath(ctx.vault, resolvedSlug);
  // The whole file, `owner:` line and body prose included, is what this
  // reader hands back - so the ownership question is asked before the
  // read, not filtered out of the bytes afterwards.
  //
  // `normalized`, not `rawId`: the absent branch above rethrows what
  // `queryByPreference` threw, and that names the NORMALISED id. This
  // reader accepts the bare slug too, so echoing the raw one here made
  // `osb://preference/acme` answer "...for id 'acme'" when the page
  // existed and was withheld, against "...for id 'pref-acme'" when it did
  // not - the presence of the prefix a one-bit existence oracle over the
  // whole reserved population.
  if (!view.refs.visible(resolvedId)) throw notFound(normalized);
  // On a store-only machine the page is the one the fold rebuilds (task 2.10).
  const stored = storeMemoryPageAt(ctx.vault, vaultRelative(filePath, ctx.vault));
  const file =
    stored === null
      ? readMarkdown(uri, filePath)
      : { uri, mimeType: MIME_MARKDOWN, text: formatFrontmatter(...stored.read()) };
  return {
    ...file,
    // The whole file - frontmatter and body - is the delivery
    // (delivery-trust, lane A): fenced at remote reach through the
    // binding, named for the page's own derived provenance; local keeps
    // the bytes. The probe asks the RESOLVED page - the id the
    // active-to-retired fallback answered - never the caller's spelling.
    text: deliveryFor(ctx, view).shape(
      file.text,
      deliveryRelForBrainArtifact(ctx.vault, resolvedId),
    ),
  };
}

export function readRuleTopic(
  ctx: ResourceContext,
  uri: string,
  rawSlug: string,
  view: RequestView,
): ResourceContent {
  if (!rawSlug.trim()) {
    throw new MCPError(INVALID_PARAMS, `topic slug must not be empty: ${uri}`);
  }
  validateSlug(rawSlug);
  let result;
  try {
    // The scope reaches the SELECTION, not the result: a topic resolves
    // to one preference and several may carry it, so filtering afterwards
    // would report the topic as having no rule whenever another owner's
    // preference happened to sort first.
    result = queryByRuleTopic(ctx.vault, rawSlug, {
      ownerScope: view.ownerScope,
      transportReach: view.reach,
    });
  } catch (err) {
    if (err instanceof BrainNotFoundError) {
      throw new MCPError(INTERNAL_ERROR, err.message);
    }
    throw err;
  }
  // The two remaining owner-bearing streams, filtered before the
  // renderer sees them: each signal row names its id and its author, and
  // the log rows are the same events `brain_event_trace` filters. A
  // topic whose ONLY rule is one this caller may not see is reported as
  // a topic with no rule, not as a topic that refused - the renderer
  // already has that shape for a topic that never reached promotion.
  const scoped = Object.freeze({
    ...result,
    signals: view.refs.keep(result.signals, (s) => [s.id]),
    all_log_events: logEntriesAtReach(view.refs, result.all_log_events),
  });
  // The synthesis is composed from spans shaped at the page each span
  // quotes (delivery-trust, lane A): the body under the governing
  // preference page's provenance - a topic with no current rule probes
  // the page that would hold it, the absent-page fail-closed answer -
  // and the objection block under the page ITS text quotes, because the
  // strongest objection may quote an agent-authored counter-signal
  // whose page is not the page that decided the body's treatment.
  const delivery = deliveryFor(ctx, view);
  const preferenceRel = result.preference
    ? deliveryRelForBrainArtifact(ctx.vault, result.preference.id)
    : `${BRAIN_PREFERENCES_REL}/pref-${rawSlug}.md`;
  const objection = ruleTopicObjectionSection(ctx.vault, scoped);
  let text: string;
  if (objection.rel === null) {
    // The block quotes the governing preference itself (or no page at
    // all): one document, one probe. The trailing newline keeps the
    // unfenced bytes identical to the pre-shaping document.
    text = delivery.shape(
      `${renderRuleTopicMarkdown(rawSlug, scoped)}\n${objection.text}\n`,
      preferenceRel,
    );
  } else {
    text =
      `${delivery.shape(renderRuleTopicMarkdown(rawSlug, scoped), preferenceRel)}\n` +
      `${delivery.shape(objection.text, objection.rel)}\n`;
  }
  return { uri, mimeType: MIME_MARKDOWN, text };
}

export function readLog(
  ctx: ResourceContext,
  uri: string,
  rawDate: string,
  view: RequestView,
): ResourceContent {
  validateIsoDate(rawDate);
  // Per-device shards (Memory Integrity Suite): a day's human view can
  // span several markdown files. The legacy single file is returned
  // verbatim (byte-identical to pre-shard behaviour); multiple shards
  // are concatenated in shard order.
  // A store-only machine has no day pages (task 2.10): the day is
  // rendered from its `log-event` records, in the shape a page has.
  const log = logDayReader(ctx.vault);
  if (log.stored) {
    // Filtered first: a day whose every event the caller may not see reads
    // as a day with none, never as an empty page (no existence oracle).
    const entries = logEntriesAtReach(view.refs, log.day(rawDate).entries);
    if (entries.length === 0) {
      throw new MCPError(INTERNAL_ERROR, `no log events for date '${rawDate}'`);
    }
    const blocks = entries.map((e) => renderLogEntryBlock(e).trimEnd());
    const text = [renderLogDayHeader(rawDate).trimEnd(), ...blocks].join(LOG_BLOCK_SEPARATOR);
    return { uri, mimeType: MIME_MARKDOWN, text: `${text}\n` };
  }
  const files = listLogMarkdownFiles(ctx.vault).filter((f) => f.date === rawDate);
  if (files.length === 0) {
    throw new MCPError(INTERNAL_ERROR, `no log file for date '${rawDate}'`);
  }
  const shard = (f: { path: string }): string =>
    shardAtReach(readFileSync(f.path, "utf8"), view.refs, () =>
      parseLogDayFile(ctx.vault, rawDate, f.path),
    );
  // The single-shard read stays verbatim (trailing newline included), so
  // a vault with the gate off is byte-identical to the pre-filter shape.
  if (files.length === 1) return { uri, mimeType: MIME_MARKDOWN, text: shard(files[0]!) };
  return { uri, mimeType: MIME_MARKDOWN, text: files.map((f) => shard(f).trimEnd()).join("\n\n") };
}

/** Start of one rendered log event: `## <time> — <kind>`. */
export const LOG_EVENT_HEADING = "\n## ";

/** The blank line {@link appendLogEvent} keeps between a shard's blocks. */
export const LOG_BLOCK_SEPARATOR = "\n\n";

/**
 * One shard as a caller behind `view` may read it: the frontmatter and
 * day heading verbatim, then the entries the Brain log event rule keeps
 * ({@link logEntriesAtReach}), each rendered as the appender writes it.
 * A shared dream keeps its readable transitions, and a retired record is
 * judged under each of its spellings, so the shard reads as it would in a
 * vault that never logged the withheld record.
 *
 * A shard is shared by construction - it is named by date and carries no
 * `owner:` - but its CONTENTS name preferences by id and by path, which
 * is why the events are filtered rather than the page.
 *
 * A block the parser cannot read is not served below local reach: what
 * it names cannot be judged, so it fails closed.
 */
export function shardAtReach(
  markdown: string,
  view: ArtifactRefView,
  parse: () => ParseLogDayResult,
): string {
  if (view.filtersNothing) return markdown;
  const firstEvent = markdown.indexOf(LOG_EVENT_HEADING);
  const head = firstEvent < 0 ? markdown : markdown.slice(0, firstEvent);
  const blocks = logEntriesAtReach(view, parse().entries).map((e) =>
    renderLogEntryBlock(e).trimEnd(),
  );
  return [head.trimEnd(), ...blocks].join(LOG_BLOCK_SEPARATOR) + "\n";
}

export function renderRuleTopicMarkdown(
  slug: string,
  result: ReturnType<typeof queryByRuleTopic>,
): string {
  const lines: string[] = [];
  lines.push(`# Brain topic: ${slug}`);
  lines.push("");
  const pref = result.preference;
  if (pref) {
    if (pref.id.startsWith("ret-")) {
      const r = pref as BrainRetired;
      const date = r.retired_at.slice(0, 10);
      lines.push("## Retired preference (no current active)");
      lines.push("");
      lines.push(`- \`${r.id}\` — retired_reason: \`${r.retired_reason}\` on ${date}`);
      lines.push(`  - ${r.principle}`);
    } else {
      const p = pref as BrainPreference;
      lines.push("## Current preference");
      lines.push("");
      lines.push(`- \`${p.id}\` — status: \`${p.status}\`, confidence: \`${p.confidence}\``);
      lines.push(`  - ${p.principle}`);
    }
    lines.push("");
  }
  const sigs = result.signals;
  if (sigs.length > 0) {
    lines.push(`## Signals (${sigs.length})`);
    lines.push("");
    for (const s of sigs) {
      lines.push(`- \`${s.id}\` — ${s.signal} signal by ${s.agent} at ${s.created_at}`);
    }
    lines.push("");
  }
  const log = result.all_log_events;
  if (log.length > 0) {
    lines.push(`## Recent log entries (${log.length})`);
    lines.push("");
    for (const e of log) {
      lines.push(`- ${e.timestamp} — \`${e.eventType}\``);
    }
    lines.push("");
  }
  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
  return lines.join("\n") + "\n";
}

/**
 * The rendered "Strongest objection" section, and the page whose
 * provenance governs it: null rel when the block quotes the governing
 * preference itself (retired, quarantined, unconfirmed) or no page at
 * all, so the document's own probe covers it; the counter-signal's own
 * page when the block quotes a negative signal's principle - agent-
 * authored text from a DIFFERENT page than the preference that decided
 * the document's treatment, which brain_query's signal payloads shape
 * at the same page.
 */
export function ruleTopicObjectionSection(
  vault: string,
  result: ReturnType<typeof queryByRuleTopic>,
): { readonly text: string; readonly rel: string | null } {
  const sentence = buildRuleTopicObjection(vault, result);
  const text = `## Strongest objection\n\n- ${sentence.sentence}`;
  return { text, rel: sentence.rel };
}

/**
 * The single best-formed reason to distrust the topic's current
 * preference, by fixed priority: an already-retired rule > a
 * quarantined rule > a recorded negative counter-signal > an
 * unconfirmed rule still in its trial window, and a "no standing
 * objection" sentence when none applies. The rel names the page the
 * sentence quotes, for the section renderer to probe.
 */
export function buildRuleTopicObjection(
  vault: string,
  result: ReturnType<typeof queryByRuleTopic>,
): { readonly sentence: string; readonly rel: string | null } {
  const pref = result.preference;
  if (pref && pref.id.startsWith("ret-")) {
    const r = pref as BrainRetired;
    return {
      sentence: `This rule was already retired (\`${r.retired_reason}\`); adopting "${r.principle}" again would repeat a judgment the Brain has discarded.`,
      rel: null,
    };
  }
  if (pref) {
    const p = pref as BrainPreference;
    if (p.status === "quarantine") {
      return {
        sentence: `The rule "${p.principle}" is on probation — recent evidence has been dominantly negative, and a single further violation retires it.`,
        rel: null,
      };
    }
  }
  const negatives = result.signals
    .filter((s) => s.signal === "negative")
    .toSorted((a, b) => (a.created_at < b.created_at ? 1 : a.created_at > b.created_at ? -1 : 0));
  if (negatives.length > 0) {
    const n = negatives[0]!;
    return {
      sentence: `A recorded counter-signal (\`${n.id}\`) argues against this: "${n.principle}". Treat the preference as contested.`,
      rel: signalDeliveryRel(vault, n.id),
    };
  }
  if (pref) {
    const p = pref as BrainPreference;
    if (p.status === "unconfirmed") {
      return {
        sentence: `The rule "${p.principle}" is unconfirmed — it has not yet earned applied evidence and may not survive its trial window (until ${p.unconfirmed_until.slice(0, 10)}).`,
        rel: null,
      };
    }
  }
  return {
    sentence:
      "No standing objection: the current preference is confirmed and faces no recorded counter-signal.",
    rel: null,
  };
}