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
/**
* Page-link to entity resolver (note-change truth maintenance, F4/C1).
*
* A source page that cites an entity page carries more than its prose:
* its outbound wikilinks name the records the page is about. This module
* turns those links into the ordered list of canonical entity ids the
* page links to, so an extraction caller can resolve them server-side
* and hand the ids to the anchoring kernel - link-derived attachment
* without pulling the link graph into the kernel itself.
*
* ## The accessor is injected, and it owns withholding
*
* The pure half ({@link pageEntityLinks}) knows nothing about vaults or
* indexes: it extracts the wikilinks in first-occurrence order
* (`extractWikilinks`, which masks code regions and skips media) and maps
* each target through the injected accessor. A target the accessor leaves
* unresolved contributes nothing, and a target it refuses is IDENTICAL TO
* ABSENT - the link-candidates convention, applied before the list is
* returned, so a withheld entity page is never leaked as an id and never
* even counts. Which pages are withheld is the caller's question, not this
* module's: the accessor is where a reach rule or an owner scope binds.
*
* {@link entityLinkResolver} is the production accessor over a vault's
* entity index. It resolves through the spellings a wikilink to an entity
* page can actually carry, in ladder order:
*
* 1. the entity id itself, with or without the `.md` suffix
* (`[[ent-people-ada-lovelace]]`, `[[ent-people-ada-lovelace.md]]`);
* 2. the page's own vault path, with or without `.md`
* (`[[Brain/entities/people/...]]`) - a spelling that carries a
* directory prefix answers ONLY as that path, never by basename
* alone, because the vault's own link resolution dangles on a
* prefixed spelling that names no page and so must this resolver;
* 3. the slug-prefixed spelling `[[people/ada-lovelace]]` - each path
* segment lowercased and its separator runs folded the way the
* anchoring kernel's separator-tolerant spelling folds them, so
* what the matcher admits and what the resolver maps agree on one
* rule. The fold is the matcher's, not the full id-minting
* slugify: a character only slugify folds (a period, an
* apostrophe) stays as written and the spelling dangles, exactly
* as the vault's own link resolution dangles on it. The rung is
* defined on the category/slug form a directory prefix carries -
* a spelling without one never reaches it;
* 4. a frontmatter alias, through the index's own alias vocabulary -
* except an alias more than one visible canonical entity claims:
* the index records that claim as a duplicate-alias conflict and
* answers it to no one, and a resolver that picked a first winner
* would turn an ambiguous link into a confident wrong anchor.
*
* Every rung answers the TRIMMED target: the shared wikilink extractor
* captures the text between the brackets untrimmed, so the whitespace a
* link carries is not part of the spelling the author wrote. The `.md`
* suffix is the one tolerance beyond that: entity ids and paths are
* answered case-sensitively, because a link is matched by its exact
* stored spelling the same way every other link read in this codebase
* matches, and a case-insensitive id map would resolve spellings the
* vault's own link resolution refuses.
*
* A bare entity NAME is deliberately not a rung: name-in-text matching is
* the anchoring kernel's job, and a link spelling the vault's own link
* resolution would dangle on stays dangling here too. Records outside the
* canonical scope (archived, quarantined, unparsable) resolve to nothing,
* exactly like absent pages, and a page the `visible` predicate refuses is
* dropped before any of its spellings can answer. An index that cannot
* build resolves nothing and never throws - a broken registry must not
* turn every page into a failed read, and it must not invent anchors
* either.
*/
import { relative, sep } from "node:path";
import { extractWikilinks } from "../../vault.ts";
import { normalizeEntityName } from "../entities/canonical.ts";
import { buildEntityIndex } from "../entities/index-builder.ts";
import { ENTITY_STATUS_SCOPE, entityStatusInScope } from "../entities/status-scope.ts";
/**
* May this wikilink target be attached as a canonical entity id? Answers
* the id, or `undefined` when the target does not resolve to an entity
* page the caller may attach - absent, non-entity, out of canonical
* scope, or withheld by the caller's reach rule.
*/
export type EntityLinkAccessor = (target: string) => string | undefined;
/**
* The ordered canonical entity ids `content` links to, in
* `extractWikilinks` first-occurrence order, deduped across spellings
* that resolve to one id. A target that resolves to nothing contributes
* nothing - including one whose accessor raises, because a link the
* resolver cannot answer is an unresolved link, not a failed page. Never
* throws; nothing to resolve answers an empty list.
*/
export function pageEntityLinks(content: string, resolve: EntityLinkAccessor): string[] {
const ids: string[] = [];
const seen = new Set<string>();
for (const target of extractWikilinks(content)) {
let id: string | undefined;
try {
id = resolve(target);
} catch {
id = undefined;
}
if (id === undefined || seen.has(id)) continue;
seen.add(id);
ids.push(id);
}
return ids;
}
export interface EntityLinkResolverOptions {
/**
* May the caller read the entity page at this VAULT-RELATIVE path?
* REQUIRED, with no default: a predicate nobody wrote must not read as
* "everything is visible", because the resolver indexes every
* canonical-scope entity it can see, and the anchor list naming an
* entity page the reader cannot read IS the disclosure. A caller
* already running at the vault's own reach (a local maintenance lane,
* the local CLI) passes `() => true` - the decision stays visible at
* the call site, and a caller deriving the list for a narrower reader
* binds its rule here. A refused page is dropped before the list is
* returned, so the refused id is not merely hidden but absent.
*/
readonly visible: (rel: string) => boolean;
}
/**
* The production {@link EntityLinkAccessor} over `vault`'s entity index,
* built once per call. Canonical-scope records only; a page the caller's
* `visible` predicate refuses is dropped before answering, under every
* spelling it answers to - and before counting as an alias claimant,
* since a refused page is identical to absent and cannot make a visible
* entity's alias ambiguous. An alias two visible entities claim is
* dropped for both, the index's own duplicate-alias rule mirrored over
* the population this accessor may name. Never throws: an index that
* cannot build answers `undefined` for every target, which is the one
* answer that cannot leak a record a broken walk cannot see.
*/
export function entityLinkResolver(
vault: string,
opts: EntityLinkResolverOptions,
): EntityLinkAccessor {
let index: ReturnType<typeof buildEntityIndex>;
try {
index = buildEntityIndex(vault);
} catch {
return () => undefined;
}
const byId = new Map<string, string>();
const byPath = new Map<string, string>();
const aliasClaims = new Map<string, Set<string>>();
for (const entity of index.entities) {
if (!entityStatusInScope(entity.status, ENTITY_STATUS_SCOPE.canonical)) continue;
const rel = relative(vault, entity.path).split(sep).join("/");
if (!opts.visible(rel)) continue;
byId.set(entity.id, entity.id);
// The page's own vault path, with and without the `.md` suffix: the
// only directory-prefixed spellings that answer (rung 2).
byPath.set(rel, entity.id);
byPath.set(rel.replace(/\.md$/i, ""), entity.id);
for (const alias of entity.aliases) {
const normalized = normalizeEntityName(alias);
if (!normalized) continue;
const claimants = aliasClaims.get(normalized) ?? new Set<string>();
claimants.add(entity.id);
aliasClaims.set(normalized, claimants);
}
}
// Contested aliases answer no one; uncontested ones answer their one
// claimant, deterministically.
const byAlias = new Map<string, string>();
for (const [normalized, claimants] of aliasClaims) {
if (claimants.size !== 1) continue;
byAlias.set(normalized, claimants.values().next().value!);
}
return (target) => {
const trimmed = target.trim();
if (byId.has(trimmed)) return trimmed;
const stripped = trimmed.replace(/\.md$/i, "");
const asPath = byPath.get(stripped);
if (asPath !== undefined) return asPath;
if (!stripped.includes("/") && byId.has(stripped)) return stripped;
// A bare spelling's rungs end here. The fold below is the
// slug-prefixed spelling's rung, defined on the category/slug form
// a directory prefix carries; folded over a bare name it would
// mint the id's own slug out of "People Ada Lovelace" or
// "people_ada_lovelace" - bare entity NAMEs, which are deliberately
// not a rung - and resolve spellings the vault's own link
// resolution dangles on. Case-varying a bare id stays unresolved
// for the same reason: ids are answered case-sensitively.
if (!stripped.includes("/")) return byAlias.get(normalizeEntityName(trimmed));
const slugPrefixed = `ent-${stripped
.split("/")
.map((segment) => segment.toLowerCase().replace(/[-_ ]+/g, "-"))
.join("-")}`;
if (byId.has(slugPrefixed)) return slugPrefixed;
return byAlias.get(normalizeEntityName(trimmed));
};
}