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
7.8 KB
Raw Blame
/**
 * Wikilink output format kernel (Workspace Insight Suite, t_5f31b5f1).
 *
 * Three explicit modes for the TARGET side of a wikilink when Open
 * Second Brain generates or normalizes notes:
 *
 *   - `preserve` (default) - links stay exactly as typed; the
 *     normalizer is the identity function.
 *   - `full` - the target is rewritten to the full vault-relative key
 *     path (`[[Brain/notes/alpha]]`).
 *   - `short` - the target is rewritten to the shortest path suffix
 *     that is unambiguous across the known pages (`[[alpha]]`, or
 *     `[[deep/beta]]` when two pages share a basename).
 *
 * Pure functions: the caller supplies the known-page list (vault-
 * relative paths without the `.md` extension). Resolution is
 * conservative - a target that does not resolve to exactly ONE known
 * page (unknown or ambiguous) is left untouched and reported, never
 * guessed. Decorations (heading anchor, block anchor, alias) and code
 * blocks are preserved verbatim; media embeds are never rewritten.
 */

export type WikiLinkFormat = "preserve" | "full" | "short";

export const WIKI_LINK_FORMATS: ReadonlyArray<WikiLinkFormat> = Object.freeze([
  "preserve",
  "full",
  "short",
]);

export function isWikiLinkFormat(value: string): value is WikiLinkFormat {
  return (WIKI_LINK_FORMATS as ReadonlyArray<string>).includes(value);
}

/** Fenced blocks and inline code spans stay verbatim on the rewrite path:
 * the regions every link reader masks. */
import { RICH_WIKILINK_RE, codeRegions } from "../wikilink.ts";

export interface NormalizeResult {
  readonly content: string;
  /** Number of links whose target side was rewritten. */
  readonly changed: number;
  /** Target sides that matched more than one known page (left as typed). */
  readonly ambiguous: ReadonlyArray<string>;
}

function stripMd(path: string): string {
  return path.endsWith(".md") ? path.slice(0, -".md".length) : path;
}

/**
 * `/`-aligned-suffix index over the known pages: every trailing-segment
 * suffix of every page maps to the (stripped) pages that carry it, in
 * `knownPaths` order. A target side `t` resolves to exactly the pages
 * where `page === t || page.endsWith("/" + t)` — precisely the bucket
 * `bySuffix.get(t)`, so per-link resolution drops from an O(pages) scan
 * (plus a fresh pages-sized array per link in the old
 * {@link shortestUniqueSuffix}) to a single Map lookup.
 */
type SuffixIndex = ReadonlyMap<string, ReadonlyArray<string>>;

/**
 * Built once per run and memoized on the `knownPaths` array identity:
 * `links normalize` walks the vault once and passes the same array to
 * every {@link normalizeWikilinks} call, so the index is built one time
 * and reused across all files instead of O(files × links) rebuilds.
 */
const SUFFIX_INDEX_MEMO = new WeakMap<ReadonlyArray<string>, SuffixIndex>();

function suffixIndex(knownPaths: ReadonlyArray<string>): SuffixIndex {
  const cached = SUFFIX_INDEX_MEMO.get(knownPaths);
  if (cached) return cached;
  const bySuffix = new Map<string, string[]>();
  for (const raw of knownPaths) {
    const page = stripMd(raw);
    const segments = page.split("/");
    // Each `take` is a distinct-length key, so a page is inserted at
    // most once per suffix (matching the old scan's single push).
    for (let take = 1; take <= segments.length; take += 1) {
      const key = segments.slice(segments.length - take).join("/");
      const list = bySuffix.get(key);
      if (list) list.push(page);
      else bySuffix.set(key, [page]);
    }
  }
  SUFFIX_INDEX_MEMO.set(knownPaths, bySuffix);
  return bySuffix;
}

/**
 * The shortest trailing-segment suffix of `path` that no other known
 * page shares. `Brain/notes/alpha` with no sibling `alpha` yields
 * `alpha`; two pages ending in `beta` yield `deep/beta` /
 * `archive/beta`.
 */
export function shortestUniqueSuffix(path: string, knownPaths: ReadonlyArray<string>): string {
  const index = suffixIndex(knownPaths);
  const segments = path.split("/");
  for (let take = 1; take <= segments.length; take += 1) {
    const suffix = segments.slice(segments.length - take).join("/");
    // `path`'s own bucket entry is always present; a clash is any OTHER
    // page sharing the suffix — identical to the old
    // `others.filter(p => p !== path).some(...)`.
    const bucket = index.get(suffix);
    const clash = bucket !== undefined && bucket.some((p) => p !== path);
    if (!clash) return suffix;
  }
  return path;
}

/**
 * Resolve a target side to the unique known page it names: an exact
 * path match or a `/`-aligned suffix match. Returns the full page
 * path, "ambiguous", or null when nothing matches.
 */
function resolveTarget(
  targetSide: string,
  knownPaths: ReadonlyArray<string>,
): string | "ambiguous" | null {
  const target = stripMd(targetSide.trim());
  if (target === "") return null;
  const matches = suffixIndex(knownPaths).get(target);
  if (matches === undefined) return null;
  if (matches.length === 1) return matches[0]!;
  if (matches.length > 1) return "ambiguous";
  return null;
}

interface BodyRewrite {
  readonly body: string;
  readonly changed: boolean;
  readonly ambiguous: string | null;
}

function rewriteBody(
  body: string,
  mode: WikiLinkFormat,
  knownPaths: ReadonlyArray<string>,
): BodyRewrite {
  if (mode === "preserve") return { body, changed: false, ambiguous: null };

  // Split decorations off verbatim: pipe binds tighter than hash in
  // the Obsidian grammar, so locate the alias first.
  const pipeIdx = body.indexOf("|");
  const aliasPart = pipeIdx >= 0 ? body.slice(pipeIdx) : "";
  const beforeAlias = pipeIdx >= 0 ? body.slice(0, pipeIdx) : body;
  const hashIdx = beforeAlias.indexOf("#");
  const anchorPart = hashIdx >= 0 ? beforeAlias.slice(hashIdx) : "";
  const targetSide = hashIdx >= 0 ? beforeAlias.slice(0, hashIdx) : beforeAlias;

  const resolved = resolveTarget(targetSide, knownPaths);
  if (resolved === null) return { body, changed: false, ambiguous: null };
  if (resolved === "ambiguous") {
    return { body, changed: false, ambiguous: targetSide.trim() };
  }
  const formatted = mode === "full" ? resolved : shortestUniqueSuffix(resolved, knownPaths);
  if (formatted === targetSide.trim()) return { body, changed: false, ambiguous: null };
  return { body: `${formatted}${anchorPart}${aliasPart}`, changed: true, ambiguous: null };
}

/** Format a single bracket body (no surrounding `[[ ]]`). */
export function formatWikilinkBody(
  body: string,
  mode: WikiLinkFormat,
  knownPaths: ReadonlyArray<string>,
): string {
  return rewriteBody(body, mode, knownPaths).body;
}

/**
 * Rewrite every wikilink in a Markdown document to the requested
 * format, skipping fenced/inline code spans and media embeds
 * (`![[...]]`).
 */
export function normalizeWikilinks(
  content: string,
  mode: WikiLinkFormat,
  knownPaths: ReadonlyArray<string>,
): NormalizeResult {
  if (mode === "preserve") {
    return Object.freeze({ content, changed: 0, ambiguous: Object.freeze([]) });
  }
  let changed = 0;
  const ambiguous = new Set<string>();

  const transformSegment = (segment: string): string =>
    segment.replace(RICH_WIKILINK_RE, (match: string, body: string, offset: number) => {
      // Media embeds (`![[...]]`) are renders, not references.
      if (offset > 0 && segment[offset - 1] === "!") return match;
      const rewrite = rewriteBody(body, mode, knownPaths);
      if (rewrite.ambiguous !== null) ambiguous.add(rewrite.ambiguous);
      if (!rewrite.changed) return match;
      changed += 1;
      return `[[${rewrite.body}]]`;
    });

  let out = "";
  let last = 0;
  for (const [start, end] of codeRegions(content)) {
    out += transformSegment(content.slice(last, start));
    out += content.slice(start, end);
    last = end;
  }
  out += transformSegment(content.slice(last));

  return Object.freeze({
    content: out,
    changed,
    ambiguous: Object.freeze([...ambiguous].toSorted()),
  });
}