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
/**
* Content visibility scoping (typed graph semantics, unit 3).
*
* A page may carry a `visibility:` frontmatter field (string or string
* array) that scopes which consumers can reach it. The rule, defined
* once here and consumed identically by the CLI and the MCP read
* surface:
*
* - A page with no `visibility:` is at DEFAULT visibility and is
* always reachable (zero behaviour change for vaults that never set
* the field).
* - A page that declares visibility values is reachable only when the
* caller's requested scope includes at least one of those values.
*
* Visibility values are opaque, language-neutral tokens (e.g. `private`,
* `team`, `agent:foo`); nothing here hardcodes a natural-language
* phrase or a closed enum.
*
* ONE of those tokens is additionally RESERVED - see
* {@link REMOTE_DENY_VISIBILITY_TOKEN} - as a controlled-vocabulary
* identifier meaning "not readable at remote reach". That is a second,
* independent question from the caller-scope rule above, answered by
* {@link isRemotelyReadable}, and the two compose: the caller's scope may
* only ever NARROW, and can no longer lift the reserved token.
*/
import { TRANSPORT_REACH, type TransportReach } from "./transport-reach.ts";
import type { FrontmatterMap } from "../types.ts";
/**
* Lower-case + NFC + trim a single visibility token. Exported because the
* MCP argument gate refuses the reserved token by its NORMALIZED form -
* a caller spelling `Private` or ` PRIVATE ` must meet the same refusal
* as one that spells the identifier exactly.
*/
export function normToken(raw: string): string {
return raw.normalize("NFC").trim().toLowerCase();
}
/**
* The visibility tokens a page declares. Empty array = default
* visibility (reachable by every consumer).
*/
export function pageVisibility(meta: FrontmatterMap): string[] {
const v = meta["visibility"];
const list = Array.isArray(v) ? v : typeof v === "string" && v.length > 0 ? [v] : [];
return list.map((s) => normToken(String(s))).filter((s) => s.length > 0);
}
/** Normalise a caller's requested visibility scope into a token set. */
export function normalizeVisibilityScope(values: ReadonlyArray<string>): Set<string> {
const out = new Set<string>();
for (const v of values) {
const t = normToken(v);
if (t) out.add(t);
}
return out;
}
/**
* Is a page with `pageTags` reachable by a caller requesting `scope`?
* Default-visibility pages (no tags) are always reachable; a tagged
* page is reachable only when one of its tags is in the requested
* scope (an empty scope reaches default pages only).
*
* The reserved token ({@link REMOTE_DENY_VISIBILITY_TOKEN}) DOMINATES:
* a page carrying it is reachable only when the scope names it too, so
* `visibility: [private, team]` is not lifted by a caller asking for
* `team`. Any-tag matching let the co-tag open the private class.
*/
export function isVisible(pageTags: ReadonlyArray<string>, scope: ReadonlySet<string>): boolean {
if (pageTags.length === 0) return true;
if (pageTags.includes(REMOTE_DENY_VISIBILITY_TOKEN)) {
return scope.has(REMOTE_DENY_VISIBILITY_TOKEN);
}
for (const t of pageTags) if (scope.has(t)) return true;
return false;
}
/**
* The one visibility token that denies a remote read.
*
* A vocabulary identifier, in the same sense as `kind: entity` or an
* entity `status` value - not a natural-language phrase, and not the head
* of a list of translations. It is written here once, already in the
* normal form {@link normToken} produces, so a page cannot spell it a
* second way and mean something else.
*
* Every OTHER token, reserved-adjacent or not, keeps exactly the
* caller-liftable semantics {@link isVisible} gives it: this constant
* reserves one identifier and defines no policy for any other.
*/
export const REMOTE_DENY_VISIBILITY_TOKEN = "private";
/**
* May a caller that reached this process at `reach` read a page carrying
* `pageTags`?
*
* Deny by default at {@link TRANSPORT_REACH.remote} for the reserved
* token, and nothing else: an untagged page, and a page carrying only
* non-reserved tokens, answer `true` at every reach and are left entirely
* to {@link isVisible}. A vault that never wrote the reserved token
* therefore sees no change from this predicate at all.
*
* `pageTags` must come from {@link pageVisibility}, which is where the
* normalisation happens; passing raw frontmatter strings would compare an
* un-normalised token against a normalised constant and silently admit a
* page that declared the reserved token in another case.
*/
export function isRemotelyReadable(
pageTags: ReadonlyArray<string>,
reach: TransportReach,
): boolean {
if (reach === TRANSPORT_REACH.local) return true;
return !pageTags.includes(REMOTE_DENY_VISIBILITY_TOKEN);
}
/**
* The stricter of two `visibility:` token lists (each already normalised
* by `pageVisibility`), for a page derived from both pages (a tension page from its two source
* notes, a preference the dream pass drafts from its signals).
*
* - Either list carries the reserved token: the reserved token alone,
* which no caller below local reach reads.
* - One list is empty (default visibility): the other one.
* - Both carry tokens: the tokens they share, so only a scope that
* reaches both pages reaches the derived one; when they share none, no
* single scope reaches both, and the reserved token is stamped.
*/
export function strictestVisibility(
a: ReadonlyArray<string>,
b: ReadonlyArray<string>,
): ReadonlyArray<string> {
const reserved = Object.freeze([REMOTE_DENY_VISIBILITY_TOKEN]);
if (a.includes(REMOTE_DENY_VISIBILITY_TOKEN) || b.includes(REMOTE_DENY_VISIBILITY_TOKEN)) {
return reserved;
}
if (a.length === 0) return Object.freeze([...b]);
if (b.length === 0) return Object.freeze([...a]);
const shared = a.filter((t) => b.includes(t));
return shared.length > 0 ? Object.freeze([...new Set(shared)]) : reserved;
}
/**
* {@link strictestVisibility} folded over any number of token lists, for a
* page derived from several pages. No lists (or only default ones) give the
* default visibility, an empty list.
*/
export function strictestVisibilityOf(
lists: ReadonlyArray<ReadonlyArray<string>>,
): ReadonlyArray<string> {
return lists.reduce<ReadonlyArray<string>>((acc, l) => strictestVisibility(acc, l), []);
}