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
9.7 KB
Raw Blame
/**
 * Resolve a reference a report row or a log event carries to the
 * vault-relative path of the page it names, or `null` when it names none
 * on disk.
 *
 * Extracted from `./artifact-ref-view.ts` so a writer below the search
 * layer can resolve references the same way: the brain store's partition
 * rule for log events (`store/reference-privacy.ts`) is reached from the
 * log appender, and the view module imports a search type the log must
 * not depend on. This module imports nothing above `brain/paths.ts`.
 */

import { isAbsolute, join } from "node:path";
import { existsSync, statSync } from "node:fs";

import { pathIsInside, posixRel, vaultRelative } from "../path-safety.ts";
import { memoryEntities, memoryFromStore, memoryRelOf } from "../store/read/memory-ids.ts";
import type { StoreEntities } from "../store/read/store-entities.ts";
import { BRAIN_DECISIONS_REL, BRAIN_SOURCES_REL, type BrainDirs, brainDirs } from "./paths.ts";
import { ANCHORED_WIKILINK_RE, stripWikilinkDecoration } from "./wikilink.ts";

/**
 * What resolving a bare id needs to know about the vault: whether its
 * memory records are read from the store (`memoryFromStore`), its Brain
 * folders (`brainDirs`) and, on a store-only machine, the store's memory
 * entities. Each reads the disk (the machine's switch state, a realpath
 * per folder, the store's shard fingerprints), so a caller that resolves many
 * references in one operation shares one scope, whose answers are worked
 * out on first use and then kept: paying them for every string of every
 * row made a batch append cost milliseconds per record.
 */
export interface ArtifactRefScope {
  readonly fromStore: () => boolean;
  readonly dirs: () => BrainDirs;
  /** The store's memory entities (`memoryEntities`), read on a store-only machine only. */
  readonly entities: () => StoreEntities | null;
}

/** A scope for `vault` that works each answer out once, on first use. */
export function artifactRefScope(vault: string, fromStore?: boolean): ArtifactRefScope {
  let store = fromStore;
  let dirs: BrainDirs | undefined;
  let entities: { readonly value: StoreEntities | null } | undefined;
  return {
    fromStore: () => (store ??= memoryFromStore(vault)),
    dirs: () => (dirs ??= brainDirs(vault)),
    entities: () => (entities ??= { value: memoryEntities({ vault }) }).value,
  };
}

/** The `.md` extension every Brain artifact id resolves through. */
const MARKDOWN_EXT = ".md";

/**
 * Strip the wikilink brackets a report row may have kept around its
 * reference, leaving the target verbatim.
 *
 * The brackets are SYNTAX, not part of the reference: a retirement's
 * `retired_by`, a dream transition's `link` and an evidence row's
 * `artifact` all carry `[[…]]` straight out of frontmatter or a log
 * body, and `[[Brain/preferences/pref-x.md]]` names exactly the page
 * `Brain/preferences/pref-x.md`. Before this, such a reference matched
 * neither branch below and the row failed OPEN.
 *
 * Deliberately NOT `parseWikilinkRich`: that normaliser collapses folder
 * segments and drops `.md`, which turns a path-shaped link into a bare
 * basename that resolves to no artifact - the same fail-open by a longer
 * route.
 *
 * The alias and anchor DO come off, through the decoration-only half of
 * that normaliser. Leaving them on was a fail-open with a comment on it:
 * `pref-x|alias`, `pref-x#Raw` and
 * `Brain/preferences/pref-x.md|the rule` end in neither `.md` nor an id
 * any directory holds, so they resolved to nothing and their rows passed
 * unconditionally - and these are not hypothetical spellings, they are
 * what `brain_apply_evidence` documents for its own `artifact` argument.
 * Cutting decoration can only ever SHORTEN the target, so a reference
 * that resolved before still resolves and one that did not may now.
 */
function unbracket(ref: string): string {
  const match = ANCHORED_WIKILINK_RE.exec(ref.trim());
  return stripWikilinkDecoration(match === null ? ref : match[1]!);
}

/**
 * Resolve a bare Brain artifact id to its vault-relative path, or `null`
 * when no artifact of that id is on disk.
 *
 * ## Why the directory list is the whole boundary
 *
 * `visible()` reads an id that resolves to no file as "this row names
 * nothing that could be hidden" and lets the row through. That reading is
 * true only for ids this function would have FOUND had the artifact
 * existed - so every directory omitted here is a directory whose pages
 * are silently unclassifiable, and every binding's fail-closed promise
 * turns into a fail-open one for exactly those pages. The list is
 * therefore every `Brain/` directory holding id-addressable Markdown:
 *
 *   - `preferences` / `retired` carry `owner:` through the preference
 *     writer, and carry `visibility:` wherever an operator wrote one;
 *   - `inbox` / `processed` / `pending` carry whatever an operator or an
 *     importer wrote into a signal's frontmatter;
 *   - `sources` (`src-<slug>.md`) and `entities` are taggable the same
 *     way, and `brain_search_by_source` already filters the first of them
 *     on the search side - so an id-shaped reference to one reaching a
 *     view here and passing was the two halves disagreeing;
 *   - `decisions` (`decision-<slug>.md`) is named by id in the
 *     decision-change receipts (`[[decision-<slug>]]`).
 *
 * `log` is deliberately absent - a log shard is named by date, is shared
 * by construction, and carries no per-page claim to read. `bases` holds
 * `.base` view definitions rather than Markdown pages, and `snapshots`
 * holds dated copies addressed by path rather than by id.
 */
function artifactPath(vault: string, id: string, scope: ArtifactRefScope): string | null {
  const dirs = scope.dirs();
  const fromStore = scope.fromStore();
  // Store-only (task 2.10): a preference or a signal is a record of the
  // folds, not a file, and still names the page it would be, so the id
  // keeps naming something the view must judge rather than nothing.
  if (fromStore) {
    const rel = memoryRelOf(scope.entities(), id);
    if (rel !== null) return rel;
  }
  const memoryDirs = fromStore
    ? []
    : [dirs.preferences, dirs.retired, dirs.inbox, dirs.processed, dirs.archived, dirs.pending];
  for (const dir of [
    ...memoryDirs,
    join(vault, BRAIN_SOURCES_REL),
    dirs.entities,
    join(vault, BRAIN_DECISIONS_REL),
  ]) {
    const abs = join(dir, `${id}${MARKDOWN_EXT}`);
    // The visibility predicate speaks vault-relative POSIX paths - the
    // form a path-shaped reference already carries. Handing it the native
    // `Brain\preferences\...` spelling on Windows would match no rule and
    // let a hidden artifact through, the fail-open this view exists to
    // prevent. Slicing the vault's length off `abs` has the same failure
    // for a vault spelled `/v/` or `/v/x/..` (`join` normalizes `abs`, not
    // `vault`), so the path is taken relative to the resolved vault.
    if (existsSync(abs)) return vaultRelative(abs, vault);
  }
  return null;
}

/**
 * The candidate an extensionless vault-page reference denotes: the bare
 * spelling when that file exists, else its `.md` twin when the twin
 * exists - the same first-existing rule the claim ledger's write side
 * applies to an extensionless source, so the read-side gate cannot drift
 * from the spelling the writer used. When neither file exists the
 * reference names nothing here (`null` reads as visible): a convention
 * like `Notes/<slug>-applied` in a log payload is not a page, and
 * judging it as a missing `.md` page would drop every row carrying it.
 * Both candidates are probed only inside the vault, so a
 * traversal-shaped reference never reaches the filesystem outside it.
 */
function pageCandidate(vault: string, bare: string): string | null {
  if (isVaultFile(vault, bare)) return bare;
  const twin = bare + MARKDOWN_EXT;
  if (isVaultFile(vault, twin)) return twin;
  return null;
}

/** The vault-relative path names a regular file, so it can name a page. */
function isVaultFile(vault: string, rel: string): boolean {
  if (!pathIsInside(join(vault, rel), vault)) return false;
  try {
    return statSync(join(vault, rel)).isFile();
  } catch {
    return false;
  }
}

/**
 * The vault-relative path `ref` names, or `null` when it names nothing on
 * disk. A reference that names a path is resolved as one, including its
 * extensionless spelling, whose .md twin is the page an Obsidian writer
 * named (a gate that resolved only the .md form failed OPEN for exactly
 * that spelling). A bare id is a Brain artifact id ({@link artifactPath}).
 * A `.md` path is returned as written, even outside the vault: the caller
 * decides what a path outside the vault means.
 *
 * Two spellings are brought to the vault-relative POSIX form first, since
 * the visibility rules and the callers' join speak only that form:
 *
 *  - on Windows a `\` is a separator (`posixRel`), so
 *    `Brain\preferences\pref-x` is the path it spells rather than a bare
 *    id that resolves to nothing;
 *  - an absolute path is made relative to the vault: one inside the vault
 *    names its page, one outside comes back climbing out of it (or
 *    absolute, on another Windows drive), which every caller refuses.
 *
 * A caller that resolves many references in one operation passes one
 * `scope` for all of them (see {@link ArtifactRefScope}).
 */
export function resolveArtifactRef(
  vault: string,
  ref: string,
  scope: ArtifactRefScope = artifactRefScope(vault),
): string | null {
  const spelled = posixRel(unbracket(ref));
  if (spelled.length === 0) return null;
  const bare = isAbsolute(spelled) ? vaultRelative(spelled, vault) : spelled;
  if (bare.length === 0) return null;
  if (bare.endsWith(MARKDOWN_EXT)) return bare;
  if (bare.includes("/")) return pageCandidate(vault, bare);
  return artifactPath(vault, bare, scope);
}