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
19.4 KB
Raw Blame
/**
 * Read-only query helpers over Brain state (design doc §9.2).
 *
 * Three callable shapes, all returning frozen result objects so the
 * surfaces consuming them (CLI `o2b brain query`, MCP `brain_query`,
 * future agent introspection) cannot accidentally mutate vault state:
 *
 *   - {@link queryByPreference} — one preference (active or retired)
 *     plus every `apply-evidence` log entry that references it.
 *
 *   - {@link queryByRuleTopic} — every signal under a topic (active +
 *     processed), the current preference for that topic (active or
 *     retired), and every log entry mentioning the preference.
 *
 *   - {@link queryByLogSince} — every log entry across all days whose
 *     `timestamp >= since`. Cron / digest / debugging entry point.
 *
 * All three are pure reads. They do not touch the inbox `processed/`
 * holding area, the snapshots/, or the `_brain.yaml` config — those are
 * dream's job.
 *
 * Wikilink resolution rule: a preference is "referenced" by a log entry
 * when the entry's `preference` payload contains either the bare id or
 * the `[[id]]` wikilink form. We strip both forms so a hand-typed entry
 * (`preference: pref-foo`) and a properly-rendered entry
 * (`preference: [[pref-foo]]`) both match.
 */

import { filterExpired, isExpired } from "./expiration.ts";
import type { BrainLogEntry } from "./log.ts";
import { memoryFolderPages, memoryPageNamed, type MemoryFolder } from "./memory-pages.ts";
import { logDayReader } from "./log-days.ts";
import { parsePreferenceMeta, parseRetiredMeta } from "./preference.ts";
import { ownerScopeView } from "./owner-scope-view.ts";
import { everyArtifactRefView, type ArtifactRefView } from "./artifact-ref-view.ts";
import { reachView } from "./reach-view.ts";
import { resolvedTransportReach, type TransportReach } from "../graph/transport-reach.ts";
import { parseSignalPage } from "./signal.ts";
import {
  SUPERSEDED_BY_KEY,
  buildChainLookup,
  isTombstoned,
  resolveChainTip,
  type ChainLookup,
} from "./lifecycle/tombstone-read.ts";
import { chainVerdict } from "../search/correction-coupling.ts";
import { vaultRelative } from "../path-safety.ts";
import { normaliseWikilinkTarget } from "./wikilink.ts";
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";
import type { BrainPreference, BrainRetired, BrainSignal } from "./types.ts";

// ----- Errors ---------------------------------------------------------------

/**
 * Raised when {@link queryByPreference} is asked for a `pref-` id (or
 * `ret-` id) that resolves to no file in either `preferences/` or
 * `retired/`. The CLI translates this to exit code `2` per design doc
 * §9.2 "not an error condition".
 */
export class BrainNotFoundError extends Error {
  readonly id: string;

  constructor(id: string) {
    super(`brain query: no preference or retired entry found for id '${id}'`);
    this.name = "BrainNotFoundError";
    this.id = id;
  }
}

// ----- Result shapes --------------------------------------------------------

export interface QueryByPreferenceResult {
  /** The active preference (`preferences/`) or retired one (`retired/`). */
  readonly preference: BrainPreference | BrainRetired;
  /**
   * Every `apply-evidence` log entry referencing this preference,
   * sorted ascending by `timestamp`. Empty when the preference exists
   * but has never been applied (common for freshly-promoted
   * unconfirmed entries).
   */
  readonly evidence: ReadonlyArray<BrainLogEntry>;
}

export interface QueryByTopicResult {
  /**
   * All signals for the topic — active (`inbox/sig-*.md`) and processed
   * (`inbox/processed/sig-*.md`). Sorted by `created_at` ascending so
   * the caller sees a chronological trail.
   */
  readonly signals: ReadonlyArray<BrainSignal>;
  /**
   * The current state of the topic's rule:
   *   - active preference if one exists in `preferences/`
   *   - retired preference if one exists in `retired/`
   *   - null if the topic has signals but never reached promotion
   *
   * A topic can plausibly have *both* an active and a retired entry
   * (the active rule supersedes a prior retired one). In that case we
   * return the active version — it is the current truth — and the
   * caller can find the historical retired one via `queryByPreference`
   * by id.
   */
  readonly preference: BrainPreference | BrainRetired | null;
  /**
   * Every log entry mentioning the topic's preference id. Sorted by
   * `timestamp` ascending. Includes `apply-evidence`, `promote`,
   * `retire`, `pin` / `unpin`, etc. — anything whose `preference`
   * payload field resolves to the same id.
   */
  readonly all_log_events: ReadonlyArray<BrainLogEntry>;
}

/**
 * Read-path options for the list surfaces (C5 / t_a82b674e). Default
 * behaviour drops any signal / preference past its `expiration_date`;
 * `showExpired` re-includes them for audit / recall of lapsed memories.
 */
export interface QueryByTopicOptions {
  /** When true, expired memories are kept in the result. Default false. */
  readonly showExpired?: boolean;
  /** Wall clock the expiration is compared against. Defaults to `new Date()`. */
  readonly now?: Date;
  /**
   * Owner scope the topic's CURRENT RULE is selected under
   * (a-label-is-not-a-boundary, U3). Absent / `null` selects as before.
   *
   * It has to reach the selection rather than filter the result,
   * because a topic resolves to exactly one preference - the first
   * match by filename - and several preferences may carry the topic.
   * Filtering afterwards would drop the row and report the topic as
   * having no rule at all, so one owner's private preference sorting
   * ahead of the shared one would HIDE the shared one from everybody
   * else. Skipping the invisible candidates during the walk returns the
   * rule this caller actually has.
   */
  readonly ownerScope?: string | null;
  /**
   * Transport reach the topic's CURRENT RULE is selected under
   * (private-is-not-a-suggestion, unit 5). Absent resolves to the
   * narrowest.
   *
   * It reaches the SELECTION for the same reason the owner scope above
   * does: a topic resolves to exactly one preference, so filtering the
   * result afterwards would report the topic as having no rule at all
   * whenever a reserved preference happened to sort ahead of a readable
   * one - hiding the readable rule from every caller.
   */
  readonly transportReach?: TransportReach;
}

// ----- Public API -----------------------------------------------------------

/**
 * Look up one preference (active or retired) and its evidence trail.
 *
 * Resolution rules:
 *   - A `pref-...` id is searched in `preferences/`. If absent, we also
 *     accept a fallback to `retired/ret-<slug>` (same slug stem) so an
 *     agent that asked for the active id of a now-retired preference
 *     still gets a useful answer.
 *   - A `ret-...` id is searched in `retired/` only.
 *   - Any other prefix raises {@link BrainNotFoundError} immediately.
 */
export function queryByPreference(vault: string, pref_id: string): QueryByPreferenceResult {
  const id = pref_id.trim();
  if (!id) {
    throw new BrainNotFoundError(pref_id);
  }
  // Slug shape is the same alphabet validateSlug() enforces; rejecting
  // here before forming any filesystem path closes a path-traversal
  // vector (`pref-../../etc/passwd`) — even though `validateSlug` would
  // catch it later, we never want `join(dirs.preferences, ...)` to
  // resolve outside the intended directory under any operator error.
  const SLUG_RE = /^[A-Za-z0-9._-]+$/;
  let preference: BrainPreference | BrainRetired | null = null;

  if (id.startsWith("pref-")) {
    const slug = id.slice("pref-".length);
    if (!SLUG_RE.test(slug)) {
      throw new BrainNotFoundError(pref_id);
    }
    const active = memoryPageNamed(vault, "preferences", `${id}.md`);
    if (active !== null) {
      preference = parsePreferenceMeta(active.read()[0], active.path);
    } else {
      // Fallback to the retired version with the same slug stem.
      const retired = memoryPageNamed(vault, "retired", `ret-${slug}.md`);
      if (retired !== null) {
        preference = parseRetiredMeta(retired.read()[0], retired.path);
      }
    }
  } else if (id.startsWith("ret-")) {
    const slug = id.slice("ret-".length);
    if (!SLUG_RE.test(slug)) {
      throw new BrainNotFoundError(pref_id);
    }
    const retired = memoryPageNamed(vault, "retired", `${id}.md`);
    if (retired !== null) {
      preference = parseRetiredMeta(retired.read()[0], retired.path);
    }
  } else {
    throw new BrainNotFoundError(pref_id);
  }

  if (!preference) {
    throw new BrainNotFoundError(pref_id);
  }

  // The evidence trail is keyed off the active id (`pref-<slug>`) — the
  // log records `preference: [[pref-<slug>]]` even after retirement.
  const slug = preference.id.startsWith("pref-")
    ? preference.id.slice("pref-".length)
    : preference.id.slice("ret-".length);
  const matchIds = new Set<string>([`pref-${slug}`, `ret-${slug}`]);

  const all = readAllLogEntries(vault);
  const evidence = all
    .filter(
      (e) =>
        e.eventType === BRAIN_LOG_EVENT_KIND.applyEvidence &&
        matchPreferencePayload(e.body["preference"], matchIds),
    )
    .toSorted(byTimestampAsc);

  return Object.freeze({
    preference,
    evidence: Object.freeze(evidence),
  });
}

/**
 * Aggregate every artifact under a topic. Includes signals across both
 * `inbox/` and `inbox/processed/`, the current rule (active or
 * retired), and every log entry mentioning the preference id (active
 * or retired form). Unknown topic → empty result with `preference: null`.
 */
export function queryByRuleTopic(
  vault: string,
  topic: string,
  options: QueryByTopicOptions = {},
): QueryByTopicResult {
  const want = topic.trim();
  if (!want) {
    return Object.freeze({
      signals: Object.freeze([]),
      preference: null,
      all_log_events: Object.freeze([]),
    });
  }

  const now = options.now ?? new Date();
  const showExpired = options.showExpired ?? false;

  let signals: BrainSignal[] = [];

  // Collect signals from inbox/, inbox/processed/ and inbox/archived/.
  // We do not recurse — those two are the only allowed sub-folders of
  // `inbox/` and `readdirSync` with `withFileTypes` lets us pick file
  // vs directory entries deterministically.
  collectSignals(vault, "inbox", want, signals);
  collectSignals(vault, "processed", want, signals);
  collectSignals(vault, "archived", want, signals);
  signals.sort((a, b) => a.created_at.localeCompare(b.created_at));
  // Expiration filter (C5): drop signals past their expiration_date
  // unless the caller opts into showExpired. The files stay on disk —
  // this is a read-path filter, orthogonal to dream retirement.
  signals = filterExpired(signals, { now, showExpired });

  // Current rule — prefer the active preference; fall back to retired.
  // Both selection rules, ANDed. They are independent questions and
  // neither is folded into the other; a candidate survives the walk only
  // when both keep it.
  const view = everyArtifactRefView(
    ownerScopeView(vault, options.ownerScope ?? null),
    reachView(vault, resolvedTransportReach(options.transportReach)),
  );
  let preference: BrainPreference | BrainRetired | null = null;
  preference = findPreferenceForTopic(vault, "preferences", want, "preference", view);
  if (!preference) {
    preference = findPreferenceForTopic(vault, "retired", want, "retired", view);
  }
  // Expiration filter (C5): an active preference past its expiration_date
  // is dropped from the default result (surfaced only under showExpired).
  // A retired preference carries no live expiration and is never filtered
  // here — it is already out of the loop.
  if (
    !showExpired &&
    preference !== null &&
    preference.kind === "brain-preference" &&
    preference.expiration_date !== undefined &&
    isExpired(preference.expiration_date, now)
  ) {
    preference = null;
  }

  // All log events whose `preference` payload resolves to the topic's
  // pref id (both `pref-` and `ret-` forms, since the slug stem is
  // shared after retirement).
  let all_log_events: ReadonlyArray<BrainLogEntry> = Object.freeze([]);
  if (preference) {
    const slug = preference.id.startsWith("pref-")
      ? preference.id.slice("pref-".length)
      : preference.id.slice("ret-".length);
    const matchIds = new Set<string>([`pref-${slug}`, `ret-${slug}`]);
    const all = readAllLogEntries(vault);
    all_log_events = Object.freeze(
      all
        .filter((e) => matchPreferencePayload(e.body["preference"], matchIds))
        .toSorted(byTimestampAsc),
    );
  }

  return Object.freeze({
    signals: Object.freeze(signals),
    preference,
    all_log_events,
  });
}

/**
 * Return every log entry across `Brain/log/*.md` whose `timestamp` is
 * `>= since` (inclusive lower bound — same semantics as the digest's
 * window). Entries are returned in chronological order. Malformed log
 * entries are silently skipped (their warnings are the doctor's
 * concern, not this surface's).
 */
export function queryByLogSince(vault: string, since: Date): ReadonlyArray<BrainLogEntry> {
  if (!(since instanceof Date) || Number.isNaN(since.getTime())) {
    throw new TypeError("queryByLogSince: `since` must be a valid Date");
  }
  const sinceIso = since.toISOString();
  const entries = readAllLogEntries(vault).filter((e) => e.timestamp >= sinceIso);
  entries.sort(byTimestampAsc);
  return Object.freeze(entries);
}

// ----- Internals ------------------------------------------------------------

/**
 * Read every log file under `Brain/log/`, parse it via {@link parseLogDay},
 * and concatenate the entries in chronological order (each file is
 * already in-order; we glue them by date prefix). Missing log directory
 * → empty array.
 */
export function readAllLogEntries(vault: string): BrainLogEntry[] {
  // Shard-aware (Memory Integrity Suite): dates from the single
  // discovery helper, entries merged across device shards.
  const out: BrainLogEntry[] = [];
  const log = logDayReader(vault);
  for (const date of log.dates) {
    const { entries } = log.day(date);
    for (const e of entries) out.push(e);
  }
  return out;
}

function collectSignals(
  vault: string,
  folder: MemoryFolder,
  topic: string,
  out: BrainSignal[],
): void {
  for (const entry of memoryFolderPages(vault, folder, { regularFilesOnly: true })) {
    if (!entry.name.startsWith("sig-") || !entry.name.endsWith(".md")) {
      continue;
    }
    const path = entry.path;
    // Belief lifecycle suite (t_7d5a3589): a tombstoned signal is
    // excluded from recall.
    const [meta, body] = entry.read();
    if (isTombstoned(meta)) continue;
    let sig: BrainSignal;
    try {
      sig = parseSignalPage(meta, body, path);
    } catch {
      // Unit F, deliberately NOT converted: this catch does not swallow a
      // frontmatter read. `parseSignal` is the typed validator and its
      // throw is a real, reachable signal (missing required field, bad
      // status/folder pairing) that `o2b brain doctor` already reports as
      // an ERROR against this exact path. Emitting a degradation notice
      // here would duplicate an existing finding at a lower severity.
      // The line-level drops underneath it are reported by the doctor's
      // Brain sweep - see src/core/vault.ts.
      continue;
    }
    if (sig.topic === topic) out.push(sig);
  }
}

/**
 * Matches on RAW topic bytes, deliberately and not yet reconciled with the
 * consolidation path: the dream pass resolves a topic through the folded
 * `topicKey`, so a caller asking for `Api-Key` finds nothing here while the
 * pass would treat it as the rule on `api-key`. Folding this lookup changes
 * which record a read returns - a recall-path behaviour change with its own
 * blast radius - so it is named rather than smuggled into a fix. The
 * condition is findable meanwhile: `o2b brain doctor` reports
 * `topic-key-collision` for preferences whose topics fold together.
 */
function findPreferenceForTopic(
  vault: string,
  folder: MemoryFolder,
  topic: string,
  kind: "preference" | "retired",
  view: ArtifactRefView,
): BrainPreference | BrainRetired | null {
  const prefix = kind === "preference" ? "pref-" : "ret-";
  // Sort by filename so the "first match" is deterministic across runs
  // and filesystems. `readdirSync` order is platform-dependent (it is
  // explicitly unspecified by POSIX and by Node) — without an explicit
  // sort, two preferences with the same topic could be returned in
  // different orders on different machines.
  const entries = memoryFolderPages(vault, folder, { regularFilesOnly: true }).toSorted((a, b) =>
    a.name.localeCompare(b.name),
  );
  // The serve-with-correction chain index, built on the first
  // pointer-bearing record and reused for the rest of the walk: a vault
  // whose records carry no pointer never pays for it.
  let chainLookup: ChainLookup | null = null;
  for (const entry of entries) {
    if (!entry.name.startsWith(prefix) || !entry.name.endsWith(".md")) {
      continue;
    }
    const path = entry.path;
    // Belief lifecycle suite (t_7d5a3589): a tombstoned entry is excluded
    // from recall while remaining on disk for audit.
    const [meta] = entry.read();
    if (isTombstoned(meta)) continue;
    try {
      const parsed =
        kind === "preference" ? parsePreferenceMeta(meta, path) : parseRetiredMeta(meta, path);
      // Skipped, not returned-then-dropped: see `ownerScope` on
      // {@link QueryByTopicOptions}.
      if (parsed.topic === topic && view.visible(parsed.id)) {
        // Serve-with-correction coupling (truth-correctable-time-aware,
        // contract item 3): a record whose frontmatter declares a
        // successor but which survived the tombstone filter - the
        // serveable-retired regime the correct verb's validity-close
        // writes - is recallable by topic only beside its resolved,
        // readable chain-tip correction, and is skipped fail-closed
        // otherwise. A record with no pointer is not in the predicate's
        // regime and keeps today's behavior.
        const pointer = meta[SUPERSEDED_BY_KEY];
        if (typeof pointer === "string" && pointer.trim() !== "") {
          chainLookup ??= buildChainLookup(vault, (rel) => view.visible(rel));
          const verdict = chainVerdict(
            vaultRelative(path, vault),
            resolveChainTip(pointer, chainLookup),
          );
          if (verdict.action === "drop") continue;
        }
        return parsed;
      }
    } catch {
      // Unit F, deliberately NOT converted - same reasoning as
      // collectSignals above: `parsePreference` / `parseRetired` throw on
      // typed validation, which the doctor already reports as an error
      // against this path. Not a swallowed frontmatter read.
      continue;
    }
  }
  return null;
}

/**
 * The `preference` payload field of an `apply-evidence` (or `promote`,
 * `retire`, …) log entry is typically a wikilink (`[[pref-foo]]`) but
 * we tolerate the bare id form and even a sub-path/alias suffix. Strip
 * brackets, drop everything after `|` or `#`, then compare against the
 * caller's set of allowed ids.
 */
function matchPreferencePayload(
  payload: string | ReadonlyArray<string> | undefined,
  matchIds: ReadonlySet<string>,
): boolean {
  if (payload === undefined) return false;
  const values = Array.isArray(payload) ? payload : [payload as string];
  for (const v of values) {
    const id = normaliseWikilinkTarget(v);
    if (id && matchIds.has(id)) return true;
  }
  return false;
}

function byTimestampAsc(a: BrainLogEntry, b: BrainLogEntry): number {
  return a.timestamp.localeCompare(b.timestamp);
}