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
/**
* Wikilink parsing helpers for the Brain layer.
*
* The Obsidian-flavoured wikilink shape is `[[target]]`, with optional
* alias (`[[target|alias]]`) and anchor (`[[target#section]]`) suffixes.
* Brain frontmatter writers always emit the bare `[[id]]` form, but the
* parsers must tolerate the alias / anchor / folder-prefixed / `.md`-
* suffixed variants because the on-disk artifacts are user-editable.
*
* Surface:
*
* - {@link normaliseWikilinkTarget} extracts the bare target id from
* any of those shapes. Used by the doctor command (resolving
* `evidenced_by` / `supersedes` pointers against the Brain index)
* and by the query command (matching log payload values against a
* preference id).
*
* - {@link parseWikilink} returns the target if the input is exactly
* a wikilink form (`^\[\[…\]\]$`), or `null` otherwise. Used by the
* dream loop's `evidenced_by` walker and the digest's tolerant
* contradiction-line parser, where the caller wants to distinguish
* "this is a wikilink" from "this is bare text".
*
* Both helpers are case-preserving and do NOT validate that the target
* exists; that's a higher-layer concern (doctor cross-references against
* the Brain index, dream relies on a follow-up `Map.has` check).
*/
import { basename } from "node:path";
/*
* Canonical wikilink regex variants.
*
* Exactly one definition of the `[[...]]` syntax exists per contract;
* every parser in the codebase imports the variant whose edge-case
* behavior it needs instead of declaring a local copy:
*
* - {@link WIKILINK_TARGET_RE}: target before any `|`/`#` suffix,
* suffix captured separately. Tolerates newlines inside the
* brackets (historical `vault.ts` behavior). For target extraction
* and merged-link rewriting.
* - {@link WIKILINK_ALIAS_RE}: target plus optional `|alias`
* capture, single-line only, `#` stays inside the target. For the
* search link/entity extractors.
* - {@link RICH_WIKILINK_RE}: whole bracket body in one capture,
* single-line only. For the link-graph parser/formatter which
* decomposes the body itself.
* - {@link WIKILINK_DETECT_RE}: presence check, no captures.
* - {@link ANCHORED_WIKILINK_RE} / {@link EXACT_WIKILINK_RE}:
* prefix-strip and whole-string forms used by the normalisers in
* this module.
*
* The `g`-flagged variants are shared module-level instances: use them
* with `matchAll`/`replace` (which do not leak `lastIndex` state);
* clone via `new RegExp(re)` before calling `exec`/`test` in a loop.
*/
/** Target capture with separate `[#|]suffix` capture; multi-line tolerant. */
export const WIKILINK_TARGET_RE = /\[\[([^\]|#]+)([#|][^\]]*)?\]\]/g;
/**
* Target plus optional `|alias` capture; single-line, unicode mode.
* The `u` flag is inherited from the entity extractor; the link
* extractor formerly ran the same pattern without it - equivalent
* here because the pattern only uses negated classes over BMP
* delimiters.
*/
export const WIKILINK_ALIAS_RE = /\[\[([^\]\n|]+?)(?:\|([^\]\n]+))?\]\]/gu;
/** Whole bracket body in one capture; single-line. */
export const RICH_WIKILINK_RE = /\[\[([^\]\n]+)\]\]/g;
/** Presence check only; no captures, not global. */
export const WIKILINK_DETECT_RE = /\[\[[^\]\n]+\]\]/u;
/** Leading-wikilink prefix strip; body in one capture. */
export const ANCHORED_WIKILINK_RE = /^\[\[([^\]]+)\]\]/;
/** Whole-string wikilink form; body in one capture. */
export const EXACT_WIKILINK_RE = /^\[\[([^\]]+)\]\]$/;
/**
* Whether the character at `index` is preceded by an ODD run of
* backslashes - the CommonMark shape of "already escaped by the author":
* `\[` renders as a literal `[`, so a sigil behind an odd run is data the
* caller already escaped, never structure. The one rule both halves of the
* wikilink family read: the neutralizer's detector skips such sigils (and
* never re-escapes them), and every link reader treats the bracket behind
* one as inert text.
*
* Pure and linear in the run length. Shared from here rather than copied
* so the detector's skip and the readers' skip cannot drift into two
* grammars.
*/
export function precededByOddBackslashRun(s: string, index: number): boolean {
let n = 0;
let i = index - 1;
while (i >= 0 && s[i] === "\\") {
n++;
i--;
}
return n % 2 === 1;
}
/**
* Whether the `[[...]]` regex match spanning `[start, end)` in `text`
* opens AND closes on live brackets: an opening or closing bracket
* preceded by an odd backslash run is escaped data, and opens or closes
* no link. `end - 2` must be the first `]` of the match's closing `]]`,
* which every pattern in this module's family guarantees.
*
* The link readers apply this to each of their matches so they agree with
* the neutralizer's detector by construction: a span the detector leaves
* (an escaped `[[`) extracts as nothing, and a span it escapes can never
* leave extractable structure behind. `text` is whatever string the
* reader ran its regex over - code-masked or raw - so the run check reads
* the same bytes the match did.
*/
export function isLiveWikilinkSpan(text: string, start: number, end: number): boolean {
if (precededByOddBackslashRun(text, start)) return false;
return !precededByOddBackslashRun(text, end - 2);
}
/** The two characters a fence is built from. */
const BACKTICK = "`";
const TILDE = "~";
/** The shortest run of fence characters that opens or closes a fence. */
const FENCE_MIN_RUN = 3;
/** A whole run of three or more fence characters: `[start, start + len)`. */
interface FenceRun {
readonly start: number;
readonly len: number;
}
/**
* Every whole run of three or more `ch`, left to right, and for each the
* run that closes it: the next run of the same character at least as long
* (next-greater-or-equal, one monotonic-stack pass from the right).
*/
function fenceClosers(text: string, ch: string): Map<number, FenceRun> {
const runs: FenceRun[] = [];
let i = text.indexOf(ch);
while (i !== -1) {
let end = i + 1;
while (end < text.length && text[end] === ch) end++;
if (end - i >= FENCE_MIN_RUN) runs.push({ start: i, len: end - i });
i = text.indexOf(ch, end);
}
const closers = new Map<number, FenceRun>();
const stack: FenceRun[] = [];
for (let r = runs.length - 1; r >= 0; r--) {
const run = runs[r]!;
while (stack.length > 0 && stack.at(-1)!.len < run.len) stack.pop();
const closer = stack.at(-1);
if (closer !== undefined) closers.set(run.start, closer);
stack.push(run);
}
return closers;
}
/**
* Every whole run of one or two backticks, left to right, and for each the
* run that closes it as an inline code span: the next run of exactly the
* same length (the CommonMark rule). One pass from the right.
*/
function inlineClosers(text: string): Map<number, FenceRun> {
const runs: FenceRun[] = [];
let i = text.indexOf(BACKTICK);
while (i !== -1) {
let end = i + 1;
while (end < text.length && text[end] === BACKTICK) end++;
if (end - i < FENCE_MIN_RUN) runs.push({ start: i, len: end - i });
i = text.indexOf(BACKTICK, end);
}
const closers = new Map<number, FenceRun>();
const nextOfLength = new Map<number, FenceRun>();
for (let r = runs.length - 1; r >= 0; r--) {
const run = runs[r]!;
const closer = nextOfLength.get(run.len);
if (closer !== undefined) closers.set(run.start, closer);
nextOfLength.set(run.len, run);
}
return closers;
}
/**
* Code regions a wikilink or mention scan masks out, as `[start, end)`
* pairs left to right: a fenced block or an inline code span. A fence is a
* whole run of three or more backticks or tildes, and it closes on the next
* whole run of the same character at least as long (the CommonMark rule),
* consumed whole: a longer fence holding a shorter run stays masked.
* Elsewhere a run of one or two backticks opens an inline span that closes
* on the next run of exactly its length. A run with no closer is not a
* region, and none of its marks opens one.
*
* One pass over the text plus one pass over the runs, so the cost is
* linear whatever the runs look like. Shared by every link and mention
* reader, so a stored excerpt never contributes links anywhere.
*/
export function codeRegions(text: string): Array<[number, number]> {
const closers = new Map([
...fenceClosers(text, BACKTICK),
...fenceClosers(text, TILDE),
...inlineClosers(text),
]);
const regions: Array<[number, number]> = [];
let i = 0;
while (i < text.length) {
const ch = text[i];
if (ch !== BACKTICK && ch !== TILDE) {
i++;
continue;
}
const closer = closers.get(i);
if (closer !== undefined) {
const end = closer.start + closer.len;
regions.push([i, end]);
i = end;
continue;
}
// An unclosed run is literal text as a whole: skipping it keeps its last
// mark from opening an inline span against an unrelated later backtick.
while (i < text.length && text[i] === ch) i++;
}
return regions;
}
/** `text` with every {@link codeRegions} region replaced by `fill(region)`. */
export function maskCodeRegions(text: string, fill: (region: string) => string): string {
let out = "";
let last = 0;
for (const [start, end] of codeRegions(text)) {
out += text.slice(last, start) + fill(text.slice(start, end));
last = end;
}
return out + text.slice(last);
}
/**
* Strip wikilink decoration off `value` and return the bare target id.
*
* Recognises:
* - surrounding `[[…]]` brackets (only the first match wins)
* - `|alias` and `#anchor` suffixes (alias / anchor dropped)
* - leading folder segments (`folder/foo` → `foo`)
* - trailing `.md` extension
*
* Returns the input unchanged (minus a trim) when it isn't decorated;
* callers can still distinguish bare text from "no input" via the empty
* string.
*/
export function normaliseWikilinkTarget(value: string): string {
let s = value.trim();
// Strip surrounding wikilink brackets, retaining only the target.
const wm = ANCHORED_WIKILINK_RE.exec(s);
if (wm) s = wm[1]!.trim();
return stripBasenameDecoration(s);
}
/**
* Drop `|alias`, `#anchor`, leading folder segments, and trailing
* `.md` from a wikilink body (everything between `[[` and `]]`).
* Shared between {@link normaliseWikilinkTarget} and
* {@link parseArtifactRef} — they apply the same Obsidian-flavoured
* resolution rules to the post-bracket part of the link.
*/
/**
* Drop a wikilink body's alias and anchor, keeping the target verbatim -
* folder segments and `.md` included.
*
* The half of {@link stripBasenameDecoration} that removes DECORATION,
* split out because a consumer that resolves a target to a vault path
* needs exactly this and must not have the other half: collapsing
* `Brain/preferences/pref-x.md|the rule` to `pref-x` turns a
* path-shaped reference into a bare basename that resolves to no file,
* which is a fail-open for any rule asked over it.
*/
export function stripWikilinkDecoration(body: string): string {
let s = body.trim();
const pipe = s.indexOf("|");
if (pipe >= 0) s = s.slice(0, pipe).trim();
const hash = s.indexOf("#");
if (hash >= 0) s = s.slice(0, hash).trim();
return s;
}
function stripBasenameDecoration(body: string): string {
let s = stripWikilinkDecoration(body);
s = basename(s);
if (s.endsWith(".md")) s = s.slice(0, -".md".length);
return s;
}
/**
* The id prefixes this Brain owns: preferences, retired records, and
* signals. Anything else a wikilink resolves to is user prose or a
* cross-layer note, and is nobody here's to flag or to prune.
*/
const BRAIN_ID_RE = /^(pref|ret|sig)-/;
/**
* Whether `target` — a bare id, normally straight out of
* {@link normaliseWikilinkTarget} — names an artifact this Brain
* manages.
*
* A predicate rather than an exported pattern: the two callers that
* asked this question each carried their own copy of the regex, which is
* one grammar in two places waiting to disagree about a fourth prefix.
* Exposing the answer instead of the pattern is what keeps it single.
*/
export function isBrainArtifactId(target: string): boolean {
return BRAIN_ID_RE.test(target);
}
/**
* The prefix a rule wears on each side of its retirement.
*
* Deliberately narrower than {@link BRAIN_ID_RE}. `sig-` is a different
* artifact, not a second spelling of the same one, so folding it away
* would merge a signal into whatever rule happens to share its slug.
* `pref-<slug>` and `ret-<slug>` are the SAME record before and after
* `moveToRetired` renamed it, which is the only reason a strip is
* correct here at all.
*/
const BRAIN_ID_PREFIX_RE = /^(?:pref-|ret-)/;
/**
* Drop the `pref-` / `ret-` prefix from a bare Brain id, leaving the slug
* both spellings share.
*
* Two call sites had grown their own copy of this pattern - the `brain
* audit` CLI verb and its MCP twin, both resolving a caller-supplied id
* onto the one audit trail that is keyed by the ORIGINAL `pref-<slug>`.
* One grammar in two files is one prefix away from disagreeing, and this
* module is where the grammar already lives.
*
* Trims before matching as well as after, so a padded argument yields the
* slug rather than falling through the pattern with its prefix intact.
*/
export function stripBrainIdPrefix(id: string): string {
return id.trim().replace(BRAIN_ID_PREFIX_RE, "").trim();
}
/**
* Fold any spelling of a Brain artifact reference onto one key.
*
* `[[pref-foo]]`, `pref-foo`, `ret-foo`, `Brain/retired/ret-foo.md` and
* `[[Brain/preferences/pref-foo.md|Foo]]` all reduce to `foo`. The
* composition is {@link normaliseWikilinkTarget} (brackets, alias,
* anchor, folder, `.md`) followed by {@link stripBrainIdPrefix} (the
* rename), which is exactly the pair a reverse lookup across a
* retirement needs on BOTH sides of the join.
*
* The prefix strip is unconditional, and that has a consequence worth
* naming rather than discovering: a basename that merely begins with one
* of the two prefixes is folded like an id, so a note called
* `ret-rospective.md` keys as `rospective`, and `pref-foo` shares a key
* with a note called `foo.md`. Both collisions are between a preference
* slug and an ordinary note basename, which is a namespace this project
* does not otherwise keep apart.
*
* A caller that cannot tolerate that must match on exact ids plus the
* `aliases:` a retirement records, rather than on a fold. This function
* is for the reverse-lookup join, where the cost of a collision is one
* extra advisory row naming a consumer that does not consume - not a
* mutation, and visible to whoever reads it.
*/
export function brainArtifactSlug(value: string): string {
return stripBrainIdPrefix(normaliseWikilinkTarget(value));
}
/**
* Return the bare target id if `value` is exactly a wikilink form
* (`^\[\[…\]\]$` modulo surrounding whitespace), otherwise `null`.
*
* Unlike {@link normaliseWikilinkTarget}, this is anchored: a bare id or
* a mixed string ("see [[foo]]" embedded in prose) yields `null`. Use
* this when "is this a wikilink at all?" is the question being asked.
*
* Alias / anchor / folder / `.md` decoration on the target itself is
* stripped via the same logic as `normaliseWikilinkTarget` so callers
* get a clean id either way.
*/
export function parseWikilink(value: string): string | null {
const m = EXACT_WIKILINK_RE.exec(value.trim());
if (!m) return null;
return normaliseWikilinkTarget(m[1]!);
}
/**
* Inclusive 1-based line range extracted from an artifact wikilink
* (`[[file:120-145]]` → `{start: 120, end: 145}`). Single-line form
* (`[[file:120]]`) returns `{start: 120, end: 120}`.
*/
export interface ArtifactRange {
readonly start: number;
readonly end: number;
}
/**
* Parse result for an `artifact` field in an `apply-evidence` event.
*
* `target` is the normalised wikilink basename (same shape as
* {@link normaliseWikilinkTarget} returns). `range` is present iff a
* well-formed `:N` or `:N-N` suffix was supplied. `malformedRange` is
* `true` when a range suffix was supplied but failed validation —
* the artifact is still recorded verbatim by the writer; the
* `brain_doctor` lint surfaces the failure separately so callers can
* fix it without losing the underlying event.
*
* Original input is preserved as `raw` so the lint message can quote
* exactly what the user wrote.
*/
export interface ArtifactRefParse {
readonly raw: string;
readonly target: string;
readonly range?: ArtifactRange;
readonly malformedRange?: true;
/** When the range suffix is present (well-formed or not). */
readonly rangeText?: string;
}
const RANGE_SUFFIX_RE = /^(.*):([^:]*)$/;
/**
* Parse the `artifact` field of an apply-evidence event.
*
* Accepts:
* - bare wikilink `[[file]]`
* - decorated `[[Folder/file.md|Alias]]`
* - **range form** `[[file:120-145]]` or `[[file:120]]`
* - bare (non-wikilink) text, in which case `target` is the
* normalised input minus any range suffix
*
* Returns a parse — `target` is always present (possibly empty for
* empty input). `range` and `malformedRange` are mutually exclusive.
*/
export function parseArtifactRef(value: string): ArtifactRefParse {
const raw = value;
// Extract the inside of `[[…]]` if present; otherwise treat the
// whole input as the target body. Keep the colon suffix here so we
// can peel the range BEFORE the basename collapse — `Folder/file:120`
// otherwise has its colon swallowed by `path.basename`.
let body = value.trim();
let wasWikilink = false;
const wm = EXACT_WIKILINK_RE.exec(body);
if (wm) {
body = wm[1]!.trim();
wasWikilink = true;
}
// Drop `|alias` before the range probe — otherwise the alias text
// sits between the colon-range and the end of the string and the
// suffix regex picks up the alias instead.
const pipe = body.indexOf("|");
if (pipe >= 0) body = body.slice(0, pipe).trim();
// Peel `:range` off the END before applying normaliseWikilinkTarget.
// The numeric heuristic keeps Windows-style paths (`C:foo`) and
// IPv6 addresses out of the range branch.
let preRange = body;
let rangeText: string | undefined;
const rm = RANGE_SUFFIX_RE.exec(body);
if (rm) {
const candidate = rm[2]!.trim();
if (wasWikilink || /^[0-9-]+$/.test(candidate)) {
preRange = rm[1]!.trim();
rangeText = candidate;
}
}
// Delegate the alias/anchor/folder/.md strip to the canonical
// wikilink normaliser so both call sites stay in sync.
const target = normaliseWikilinkTarget(preRange);
if (rangeText === undefined) {
return { raw, target };
}
const range = validateRangeText(rangeText);
if (range === null) {
return { raw, target, rangeText, malformedRange: true };
}
return { raw, target, rangeText, range };
}
/**
* Maximum length of the wikilink title rendered by {@link renderPrefLink}
* before truncation kicks in. Chosen so a `[[pref-…|title]]` link fits on
* one Obsidian list-row at typical viewport widths.
*/
export const MAX_PREF_LINK_TITLE_LEN = 80;
/**
* Render a wikilink to a Brain preference or retired artifact with a
* human-readable title sourced from the `principle` field.
*
* The title is NFC-normalised, whitespace-collapsed, sanitised of
* wikilink-breaking characters (`[`, `]`, `|`), and truncated to
* {@link MAX_PREF_LINK_TITLE_LEN} at a word boundary (ellipsised when
* cut). When the principle is missing or becomes empty after
* sanitisation, the helper falls back to the bare `[[id]]` form so the
* link remains resolvable through {@link normaliseWikilinkTarget} and
* {@link parseWikilink} (both of which already strip `|alias`).
*
* Used by every Brain writer that emits a pref / retired reference;
* signal and external-artifact wikilinks stay bare-id because they have
* no useful title source.
*/
/** Where a wikilink renders to: Obsidian `[[wikilink]]` or portable `[markdown](path)`. */
export type LinkOutputFormat = "wikilink" | "markdown";
export function renderPrefLink(input: {
readonly id: string;
readonly principle?: string;
readonly format?: LinkOutputFormat;
readonly targetPath?: string;
}): string {
const raw = input.principle ?? "";
// Sanitisation pipeline, in order:
// 1. NFC normalise so visually-equal inputs hash to the same bytes.
// 2. Strip C0/C1 control chars except tab/newline (the whitespace
// collapse below handles those), zero-width joiners, BiDi
// overrides — these can spoof or break Obsidian rendering.
// 3. Replace wikilink-breaking glyphs (`[`, `]`, `|`) with spaces.
// 4. Collapse all whitespace runs to a single space, trim.
const title = raw
.normalize("NFC")
.replace(/\r\n?/g, "\n")
// C0 controls (00-1F) except \t \n; DEL (7F); C1 controls (80-9F).
// eslint-disable-next-line no-control-regex
.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, " ")
// Format / BiDi-override characters that can cause visual spoofing
// in Obsidian: zero-width space/joiner, LRM/RLM, BiDi embedding +
// override + isolates, soft hyphen, BOM.
.replace(/[---]/g, " ")
.replace(/[[\]|]/g, " ")
.replace(/\s+/g, " ")
.trim();
if (title.length === 0) {
if (input.format === "markdown") {
return renderMarkdownLink(input.id, inferBrainArtifactPath(input.id, input.targetPath));
}
return `[[${input.id}]]`;
}
// Measure the cap against code-point count (Array.from yields one
// entry per Unicode scalar) rather than UTF-16 code units so a
// string of 50 astral glyphs (100 code units, 50 code points) is
// not forced into the truncation path when the cap is 80.
const codepoints = Array.from(title);
if (codepoints.length <= MAX_PREF_LINK_TITLE_LEN) {
if (input.format === "markdown") {
return renderMarkdownLink(title, inferBrainArtifactPath(input.id, input.targetPath));
}
return `[[${input.id}|${title}]]`;
}
// Truncate to the cap, then back off to the previous word boundary —
// but only when one exists inside the window. A single oversized token
// (no space inside the cap) gets a hard cut so we still produce a link
// rather than dropping back to the bare-id fallback. Slicing happens
// on code points so an emoji or astral glyph never gets bisected
// into a lone surrogate before the ellipsis.
let cutPoints = codepoints.slice(0, MAX_PREF_LINK_TITLE_LEN);
const lastSpace = cutPoints.lastIndexOf(" ");
if (lastSpace > 0) cutPoints = cutPoints.slice(0, lastSpace);
const truncated = `${cutPoints.join("")}…`;
if (input.format === "markdown") {
return renderMarkdownLink(truncated, inferBrainArtifactPath(input.id, input.targetPath));
}
return `[[${input.id}|${truncated}]]`;
}
function inferBrainArtifactPath(id: string, targetPath?: string): string {
if (targetPath) return targetPath;
if (id.startsWith("ret-")) return `Brain/retired/${id}.md`;
if (id.startsWith("pref-")) return `Brain/preferences/${id}.md`;
return `Brain/${id}.md`;
}
function renderMarkdownLink(label: string, targetPath: string): string {
return `[${label}](${encodeMarkdownTarget(targetPath)})`;
}
function encodeMarkdownTarget(targetPath: string): string {
return encodeURI(targetPath).replace(/\)/g, "%29");
}
function validateRangeText(text: string): ArtifactRange | null {
// Accepts `N` or `N-N`, both with 1-based positive integers and
// `end >= start`. Anything else fails (zero, negative numbers,
// reversed range, dangling dashes).
const single = /^\d+$/.exec(text);
if (single) {
const n = parseInt(text, 10);
if (n <= 0) return null;
return { start: n, end: n };
}
const pair = /^(\d+)-(\d+)$/.exec(text);
if (!pair) return null;
const start = parseInt(pair[1]!, 10);
const end = parseInt(pair[2]!, 10);
if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
if (start <= 0 || end <= 0) return null;
if (end < start) return null;
return { start, end };
}