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
/**
* How a tool result names a path on this machine, at the caller's reach
* (task 2.10, design D14).
*
* Once a machine writes to the brain store only, a tool result can name a
* path outside the vault: a store shard (an attestation record), the
* device-local machine state (snapshots, artifacts, payloads, workruns,
* the digest cache, files restored from the migration backup) or the
* store and its state directory themselves (`second_brain_status`).
* {@link vaultRelativeSafe} keeps such a path as it is, and an absolute
* host path tells a remote caller the home directory, the user name and
* the layout of this machine.
*
* So the one rule, beside `vaultRelativeSafe`:
*
* - a path inside the vault is vault-relative and forward-slash, at
* every reach, exactly as `vaultRelativeSafe` answers;
* - at local reach (a caller that already holds filesystem-equivalent
* access) any other path stays as it is;
* - at remote reach a store path is `store:<partition>/<relative path>`,
* a device-local path is `local:<relative path>`, and any other
* absolute path is {@link REDACTED_DEVICE_PATH}.
*
* {@link pathsForCaller} applies the rule to a whole tool result on its
* way out (`server.ts`), so a field that names a host path as its value
* (`absolute_path`, `config_path`, a surface list) cannot reach a remote
* caller even when its tool forgot `toolPath`. It rewrites a string that
* IS an absolute path under one of this machine's roots (the vault, the
* store, the device state, the home, the temp, the config and the human
* view folders), and every such path a longer string mentions (a check
* message, a warning, error prose, a resource body). A string that is
* itself JSON text is rewritten parsed and serialized again, so a path it
* spells with escapes (a Windows path's doubled backslashes) is found too. Only those roots are matched,
* each as a whole path segment: a path that merely looks like one (a URL
* path, `/etc/hosts`, another user's home quoted in a note) stays as it
* is. The operator's
* `expose_host_paths` keeps every path raw.
*/
import { realpathSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { dirname, isAbsolute, posix, relative, resolve } from "node:path";
import { resolveExposeHostPaths } from "../../core/config.ts";
import { TRANSPORT_REACH, type TransportReach } from "../../core/graph/transport-reach.ts";
import { toPosix } from "../../core/path-safety.ts";
import { deviceLocalStateRoot } from "../../core/state/machine-state.ts";
import {
isPathInside,
isPathInsideResolved,
resolveConfiguredStoreRoot,
storesStateDir,
} from "../../core/store/store-paths.ts";
import { processDirsEnv } from "../../core/platform-dirs.ts";
import { configuredViewTargetDir } from "../../core/view/target.ts";
import { redactErrorForCaller } from "../error-redaction.ts";
import { contextReach, contextVault, type ServerContext } from "../tool-contract.ts";
import { vaultRelativeSafe } from "./shared.ts";
/** Prefix of a path inside the brain store: `store:<partition>/<relative path>`. */
export const STORE_PATH_PREFIX = "store:";
/** Prefix of a path in this machine's device-local state: `local:<relative path>`. */
export const LOCAL_PATH_PREFIX = "local:";
/** What a remote caller is told for an absolute path that is neither. */
export const REDACTED_DEVICE_PATH = "<device-path>";
/** The roots a remote answer is told relative to, most specific first. */
interface DeviceRoot {
readonly root: string;
readonly prefix: string;
}
function deviceRoots(configPath: string | undefined): DeviceRoot[] {
const roots: DeviceRoot[] = [];
// Each root is best effort: a config that cannot be read names no
// store, and the path it would have matched is redacted instead.
try {
roots.push({ root: resolveConfiguredStoreRoot(configPath).root, prefix: STORE_PATH_PREFIX });
} catch {
// See above.
}
try {
roots.push({ root: deviceLocalStateRoot(configPath), prefix: LOCAL_PATH_PREFIX });
} catch {
// See above.
}
roots.push({ root: storesStateDir(processDirsEnv()), prefix: LOCAL_PATH_PREFIX });
return roots;
}
function relativePosix(root: string, target: string): string {
const rel = toPosix(relative(resolve(root), resolve(target)));
return rel === "" ? "." : posix.normalize(rel);
}
/**
* The path `target` as a tool result at `reach` names it. `vault` is the
* vault the tool serves (`null`: none); `configPath` the machine config
* the store root comes from (default: the resolved one).
*/
export function reportedPath(
vault: string | null,
target: string,
reach: TransportReach,
configPath?: string,
): string {
if (!isAbsolute(target)) return target;
if (vault !== null && isPathInsideResolved(target, vault, process.platform)) {
return vaultRelativeSafe(vault, target);
}
if (reach === TRANSPORT_REACH.local) return target;
for (const { root, prefix } of deviceRoots(configPath)) {
if (isPathInsideResolved(target, root, process.platform)) {
return `${prefix}${relativePosix(root, target)}`;
}
}
return REDACTED_DEVICE_PATH;
}
/** {@link reportedPath} for the vault, reach and config of a tool's context. */
export function toolPath(ctx: ServerContext, target: string): string {
return reportedPath(contextVault(ctx), target, contextReach(ctx), ctx.configPath ?? undefined);
}
/**
* The `store` status block (`second_brain_status`) as a caller at the
* context's reach may see it: at remote reach the store root, each
* partition and the device state directory are named by
* {@link reportedPath}, and the reason of an unusable store is redacted
* like any error prose. At local reach the block is returned as built.
*/
export function storeStatusForCaller(
ctx: ServerContext,
block: Record<string, unknown>,
): Record<string, unknown> {
const reach = contextReach(ctx);
if (reach === TRANSPORT_REACH.local) return block;
const name = (target: unknown): unknown =>
typeof target === "string" ? toolPath(ctx, target) : target;
const located = (entry: unknown): unknown =>
typeof entry === "object" && entry !== null && "path" in entry
? { ...entry, path: name((entry as { path: unknown }).path) }
: entry;
const out: Record<string, unknown> = { ...block };
if ("root" in out) out["root"] = located(out["root"]);
if ("device_state_dir" in out) out["device_state_dir"] = located(out["device_state_dir"]);
if (Array.isArray(out["partitions"])) out["partitions"] = out["partitions"].map(located);
if (typeof out["error"] === "string") {
out["error"] = redactErrorForCaller(out["error"], contextVault(ctx) ?? "", reach);
}
return out;
}
/** Every spelling of `path` a value may carry: as given and resolved through links. */
function spellings(path: string): string[] {
try {
const real = realpathSync(path);
return real === path ? [path] : [path, real];
} catch {
return [path];
}
}
/** The roots a host path in a result can sit under, each in every spelling. */
function callerRoots(vault: string | null, configPath: string | undefined): string[] {
const roots = [homedir(), tmpdir(), ...deviceRoots(configPath).map((r) => r.root)];
if (vault !== null) roots.push(vault);
// The human view folder may sit under none of the others; a path in it
// is redacted like any other device path. Best effort, as above.
try {
const view = configuredViewTargetDir(configPath);
if (view !== null) roots.push(view);
} catch {
// An unreadable config names no view folder.
}
if (configPath !== undefined) roots.push(dirname(resolve(configPath)));
// An empty or relative root names no place; a root of `/` (or a drive
// root) would claim every absolute path.
return [...new Set(roots.filter((root) => isAbsolute(root)).flatMap(spellings))].filter(
(root) => resolve(root) !== dirname(resolve(root)),
);
}
/**
* Whether the operator asked for raw host paths (`expose_host_paths`, the
* escape hatch `vault_path` honours too). A config that cannot be read
* keeps them redacted.
*/
function exposesHostPaths(configPath: string | undefined): boolean {
try {
return resolveExposeHostPaths(configPath);
} catch {
return false;
}
}
function isPlainObject(value: unknown): value is Record<string, unknown> {
if (value === null || typeof value !== "object") return false;
const proto = Object.getPrototypeOf(value) as unknown;
return proto === Object.prototype || proto === null;
}
/**
* `result` with every string that is an absolute path under one of this
* machine's roots named by {@link reportedPath} at `reach` (see the module
* header). At local reach the result is returned as it is.
*/
export function pathsForCaller<T>(
result: T,
vault: string | null,
reach: TransportReach,
configPath?: string,
): T {
if (reach === TRANSPORT_REACH.local || exposesHostPaths(configPath)) return result;
let roots: string[] | null = null;
let mention: RegExp | null = null;
const named = new Map<string, string>();
const rootsNow = (): string[] => (roots ??= callerRoots(vault, configPath));
const report = (path: string): string => {
const known = named.get(path);
if (known !== undefined) return known;
const out = reportedPath(vault, path, reach, configPath);
named.set(path, out);
return out;
};
const name = (value: string): string => {
const json = jsonText(value);
if (json !== null) return json;
if (isAbsolute(value) && !/[\r\n]/.test(value)) {
if (rootsNow().some((root) => isPathInside(value, root, process.platform))) {
// The vault root itself: a field never reads as missing.
const reported = report(value);
return reported === "" ? VAULT_IN_PROSE : reported;
}
}
const folded = foldCase(value);
if (!rootsNow().some((root) => folded.includes(foldCase(root)))) return value;
mention ??= mentionPattern(rootsNow());
return value.replace(mention, (token: string) => {
// Sentence punctuation after a path is not part of it.
const path = token.replace(/[.:!?]+$/, "");
const reported = report(path);
return `${reported === "" ? VAULT_IN_PROSE : reported}${token.slice(path.length)}`;
});
};
// A string that is itself JSON text (a resource body) spells a path with
// escapes: every backslash of a Windows path doubled, a forward slash
// possibly as `\/`. Its strings are rewritten parsed, then serialized
// again in the layout the text had.
const jsonText = (value: string): string | null => {
const head = value.trimStart()[0];
if (head !== "{" && head !== "[") return null;
let parsed: unknown;
try {
parsed = JSON.parse(value);
} catch {
return null;
}
const walked = walk(parsed);
if (JSON.stringify(walked) === JSON.stringify(parsed)) return value;
const trailing = /\r?\n$/.exec(value)?.[0] ?? "";
return `${JSON.stringify(walked, null, jsonIndent(value))}${trailing}`;
};
const walk = (value: unknown): unknown => {
if (typeof value === "string") return name(value);
if (Array.isArray(value)) return value.map(walk);
if (!isPlainObject(value)) return value;
// `Object.fromEntries` defines own properties, so a `__proto__` key a
// parsed JSON body carries stays a key and never sets a prototype.
return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, walk(item)]));
};
return walk(result) as T;
}
/** The indent of a JSON text: the whitespace that opens its second line, if any. */
function jsonIndent(text: string): string | undefined {
return /^\s*[[{]\r?\n([ \t]+)/.exec(text)?.[1];
}
/** How prose names the vault root itself (its vault-relative form is empty). */
const VAULT_IN_PROSE = "<vault>";
/** Whether paths on this platform's default filesystems ignore case. */
const CASE_FOLDS = process.platform === "win32" || process.platform === "darwin";
/** `text` case folded where the filesystem folds case, as `isPathInside` compares. */
function foldCase(text: string): string {
return CASE_FOLDS ? text.toLowerCase() : text;
}
/**
* A path under one of `roots` where it sits in prose: the root as a whole
* path segment on both sides (so `/home/al` never matches inside
* `/home/alice`, and `/tmp` never inside `/var/tmp` or a URL path: the
* root starts the text or follows whitespace, a quote, a bracket, one of
* `=,;` or a `file://` scheme), then the rest of the path up to whitespace, a quote or a
* bracket. A backslash continues a path on Windows only; on POSIX it is a
* character of the text. Case folded where the filesystem folds it.
* Longest root first, so the most specific one names it.
*/
function mentionPattern(roots: ReadonlyArray<string>): RegExp {
const win = process.platform === "win32";
const spelled = new Set<string>();
for (const root of roots) {
const trimmed = root.replace(/[\\/]+$/, "");
spelled.add(trimmed);
if (win) spelled.add(trimmed.replaceAll("\\", "/"));
}
const alternatives = [...spelled]
.toSorted((a, b) => b.length - a.length)
.map((root) => root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
const sep = win ? "[\\\\/]" : "/";
const rest = win ? "[^\\s'\"`<>|,;()\\[\\]{}]*" : "[^\\s'\"`<>|,;()\\[\\]{}\\\\]*";
return new RegExp(
`(?:(?<=file://)|(?<=file:///)|(?<![^\\s'"\`(\\[{<=,;]))(?:${alternatives.join("|")})(?=$|${sep}|[\\s'"\`:,;()\\[\\]<>{}.!?])(?:${sep}${rest})?`,
CASE_FOLDS ? "gi" : "g",
);
}