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
/**
* The partition of a dual-written record that names pages rather than
* being one: a Brain log event names preferences and other pages through
* ids and wikilinks, and a truth claim names the page it was taken from.
* A record that names a private page goes to `private` only. On a machine
* without that partition the appender refuses it and the refusal is
* counted, so a private page's id, principle or facts never reach
* `shared`, the partition every machine syncs.
*
* Every page is judged by {@link isPrivatePageFile}, the rule every other
* brain dual-write site uses: a page that exists but cannot be read counts
* as private. A reference that can only mean a page fails closed when it
* resolves to none, because a page that is not there cannot be judged:
*
* - a preference id (`pref-<slug>` or `ret-<slug>`, bare or as a link)
* with neither its active nor its retired page on disk;
* - a claim source written as a wikilink or a `.md` path that names no
* file in the vault.
*
* Any other string a log event carries (an artifact such as
* `[[src/cli/main.ts:120-145]]`, a log shard link, free text) is resolved
* by the reference reader the log's per-reader views use
* (`brain/artifact-ref-resolve.ts`): when it names a page, that page is
* judged, and when it names none it names nothing private. A claim source
* that is neither a wikilink nor a `.md` path (a URL, free text) is judged
* only when it names a file.
*
* Store-only machines (design D14 item 18, `store-privacy.ts`): once a
* machine writes to the store only, a preference or signal reference is
* judged from the store's folds, never from the legacy pages, and one the
* folds cannot resolve is private. With no vault at all (`null`), a
* reference that can only name a page (a wikilink or a `.md` path) cannot
* be judged and is private; free text names nothing.
*/
import { existsSync, statSync } from "node:fs";
import { resolve } from "node:path";
import {
type ArtifactRefScope,
artifactRefScope,
resolveArtifactRef,
} from "../brain/artifact-ref-resolve.ts";
import { resolveNotePath } from "../brain/note-path.ts";
import { BRAIN_PREFERENCES_REL, BRAIN_RETIRED_REL } from "../brain/path-constants.ts";
import { preferencePath, retiredPath } from "../brain/paths.ts";
import { extractId } from "../brain/temporal/period-common.ts";
import { pathIsInside } from "../path-safety.ts";
import { extractWikilinks } from "../vault.ts";
import {
ANCHORED_WIKILINK_RE,
stripBrainIdPrefix,
stripWikilinkDecoration,
} from "../brain/wikilink.ts";
import { isPrivatePageFile } from "./dual-write-records.ts";
import { rowStrings, textCarriesPrivateRegion } from "./private-region.ts";
import {
judgesFromStore,
signalIdOf,
storePreferenceIdIsKnownPrivate,
storePreferenceIdIsPrivate,
storeSignalIdIsPrivate,
} from "./store-privacy.ts";
/** Extension of a vault page. */
const PAGE_EXTENSION = ".md";
/** Whether `ref` can only name a page: a wikilink, or a `.md` path. */
function namesAPage(ref: string): boolean {
const trimmed = ref.trim();
return ANCHORED_WIKILINK_RE.test(trimmed) || trimmed.endsWith(PAGE_EXTENSION);
}
/**
* Whether the preference `id` names is private: its active or retired page
* is, or neither page is on disk (it cannot be judged).
*/
function preferenceIdIsPrivate(
vault: string | null,
id: string,
fromStore: boolean = vault === null || judgesFromStore(vault),
): boolean {
if (fromStore || vault === null) return storePreferenceIdIsPrivate(id);
let paths: string[];
try {
const slug = stripBrainIdPrefix(id);
paths = [preferencePath(vault, slug), retiredPath(vault, slug)].filter((p) => existsSync(p));
} catch {
return true; // a slug no page can carry: nothing to judge
}
return paths.length === 0 || paths.some((p) => isPrivatePageFile(p));
}
/** The folders a preference page lives in, vault-relative. */
const PREFERENCE_DIRS: ReadonlySet<string> = new Set([BRAIN_PREFERENCES_REL, BRAIN_RETIRED_REL]);
/**
* The preference id a path-shaped reference names on a store-only machine
* (`Brain/preferences/pref-x.md`, `[[Brain/retired/ret-x]]`), or
* `undefined`. Only a path in a preference folder counts: a note that
* happens to be called `pref-x` elsewhere is judged as the page it is.
*/
function preferenceIdOfPath(ref: string): string | undefined {
const trimmed = ref.trim();
const anchored = ANCHORED_WIKILINK_RE.exec(trimmed);
const target = stripWikilinkDecoration(anchored !== null ? anchored[1]! : trimmed)
.replaceAll("\\", "/")
.replace(/\.md$/, "");
const slash = target.lastIndexOf("/");
if (slash === -1 || !PREFERENCE_DIRS.has(target.slice(0, slash))) return undefined;
return extractId(target.slice(slash + 1));
}
/**
* Whether a Brain log event names a private page, given the references it
* carries (`logEntryArtifactRefs` in `brain/log.ts`, which passes them so
* this module needs no import of the log). `guessed` is the preference a
* reconcile event's topic would be: a guess from the topic name, not a
* reference the event carries, so it is judged only when its page exists.
* Read only when dual writes are on; see the module docblock for the rule.
*/
export function logRefsNamePrivatePage(
vault: string | null,
refs: ReadonlyArray<string | undefined>,
guessed?: string,
): boolean {
return refsNamePrivatePage(vault, refs, guessed, vault === null || judgesFromStore(vault));
}
/** {@link logRefsNamePrivatePage} with the store-only verdict worked out once by the caller. */
function refsNamePrivatePage(
vault: string | null,
refs: ReadonlyArray<string | undefined>,
guessed: string | undefined,
fromStore: boolean,
scope?: ArtifactRefScope,
): boolean {
// Only the guess itself is spared the missing-page rule: the same id
// written into the event's body is a reference it carries, judged like
// any other.
let guessSpared = guessed === undefined;
for (const ref of refs) {
if (ref === undefined || ref === "") continue;
const isGuess = !guessSpared && ref === guessed;
if (isGuess) guessSpared = true;
// On a store-only machine a path to a preference page is the
// preference too: the fold judges it, never the legacy page.
const id = extractId(ref) ?? (fromStore ? preferenceIdOfPath(ref) : undefined);
if (id !== undefined && !isGuess && preferenceIdIsPrivate(vault, id, fromStore)) return true;
if (fromStore) {
// The folds, not the legacy pages, say what a preference or a signal is.
const signal = signalIdOf(ref);
if (signal !== undefined) {
if (storeSignalIdIsPrivate(signal)) return true;
continue;
}
if (id !== undefined) {
if (isGuess && storePreferenceIdIsKnownPrivate(id)) return true;
continue;
}
}
if (vault === null) {
if (namesAPage(ref)) return true;
continue;
}
const rel = resolveArtifactRef(vault, ref, scope ?? artifactRefScope(vault, fromStore));
if (rel === null) continue;
// A path outside the vault names no page anyone may be shown. `resolve`,
// not `join`: a relative path stays under the vault either way, and an
// absolute one is judged where it is rather than glued onto the vault.
const abs = resolve(vault, rel);
if (!pathIsInside(abs, vault) || (existsSync(abs) && isPrivatePageFile(abs))) return true;
}
return false;
}
/**
* Whether a truth claim's source is a private page. The source resolves
* the way the claim ledger resolves it for its validity window
* (`brain/truth/store.ts`): the wikilink body or the string as given,
* tried as is and then with `.md`, inside the vault only.
*/
export function claimSourceIsPrivate(vault: string | null, source: string): boolean {
const trimmed = source.trim();
const anchored = ANCHORED_WIKILINK_RE.exec(trimmed);
const target = stripWikilinkDecoration(anchored !== null ? anchored[1]! : trimmed);
if (target === "") return false;
const pageRef = anchored !== null || target.endsWith(PAGE_EXTENSION);
const fromStore = vault === null || judgesFromStore(vault);
const id = extractId(target) ?? (fromStore ? preferenceIdOfPath(target) : undefined);
if (id !== undefined) return preferenceIdIsPrivate(vault, id, fromStore);
if (fromStore) {
const signal = signalIdOf(target);
if (signal !== undefined) return storeSignalIdIsPrivate(signal);
}
if (vault === null) return pageRef;
const candidates = target.endsWith(PAGE_EXTENSION) ? [target] : [target, target + PAGE_EXTENSION];
for (const candidate of candidates) {
let path: string;
try {
path = resolveNotePath(vault, candidate, { mustExist: false });
} catch {
// Outside the vault: no page anyone may be shown.
return pageRef;
}
try {
if (!statSync(path).isFile()) continue;
} catch {
continue;
}
return isPrivatePageFile(path);
}
return pageRef;
}
/**
* Whether a pinned-context text must stay out of `shared`: it carries a
* `<private>` region or the placeholder a stripped one leaves (the pinned
* writer strips regions before it writes, as continuity does), or one of
* its wikilinks names a private page (judged as a log event's references
* are, {@link logRefsNamePrivatePage}).
*/
export function pinnedTextIsPrivate(vault: string | null, text: string): boolean {
if (textCarriesPrivateRegion(text)) return true;
return logRefsNamePrivatePage(
vault,
extractWikilinks(text).map((target) => `[[${target}]]`),
);
}
/**
* Whether a ledger row names a private page, so its store copy goes to
* `private` only. Every string the row carries, at any depth, is checked
* for a `<private>` region or the placeholder a stripped one leaves. Every
* string outside an `opaque` field is also judged as a reference: a
* wikilink inside free text, and the string itself as a preference id, a
* page path or an artifact id, by the rules of {@link pinnedTextIsPrivate}
* and {@link logRefsNamePrivatePage}. A preference id whose page is not on
* disk cannot be judged and counts as private, as does a path outside the
* vault.
*
* `opaque` names the fields whose values are not references at any depth:
* a client's idempotency key, a payload hash, a timestamp, an allocated
* id. Such a value is chosen by a client or a hash function, not written
* to name a page, so a key spelled `pref-unused` names no preference and
* cannot make an open item's row private. Read only when dual writes are
* on.
*/
export function rowNamesPrivatePage(
vault: string | null,
row: unknown,
opaque: ReadonlySet<string> = new Set(),
): boolean {
return rowPrivacyJudge(vault)(row, opaque);
}
/** Judges rows by {@link rowNamesPrivatePage}; see {@link rowPrivacyJudge}. */
export type RowPrivacyJudge = (row: unknown, opaque?: ReadonlySet<string>) => boolean;
/**
* A judge of many rows of one operation by {@link rowNamesPrivatePage}:
* the machine's store-only verdict is worked out once, when the judge is
* made, and every distinct reference string is judged once however many
* rows carry it. A batch append (a session's turns, a sweep of imports)
* repeats the same roles, kinds, session ids and timestamps on every row;
* judging each again, with the switch state and the Brain folders
* re-read from disk each time, cost milliseconds per record. A judge lives for one operation only, so
* the verdicts it remembers are those of the moment the operation ran.
*/
export function rowPrivacyJudge(vault: string | null): RowPrivacyJudge {
let fromStore: boolean | undefined;
let scope: ArtifactRefScope | undefined;
const verdicts = new Map<string, boolean>();
const refIsPrivate = (ref: string): boolean => {
let verdict = verdicts.get(ref);
if (verdict === undefined) {
fromStore ??= vault === null || judgesFromStore(vault);
if (vault !== null) scope ??= artifactRefScope(vault, fromStore);
verdict = refsNamePrivatePage(vault, [ref], undefined, fromStore, scope);
verdicts.set(ref, verdict);
}
return verdict;
};
return (row, opaque = new Set()) => {
const strings = rowStrings(row, opaque);
if (strings === null) return true;
if (strings.texts.some(textCarriesPrivateRegion)) return true;
if (strings.references.length === 0) return false;
if (strings.references.some(textCarriesPrivateRegion)) return true;
const linked = strings.references.flatMap((text) =>
extractWikilinks(text).map((target) => `[[${target}]]`),
);
return linked.some(refIsPrivate) || strings.references.some(refIsPrivate);
};
}