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
/**
* Vault graph export/import (Vault portability suite, Feature 5).
*
* `exportVaultGraph` serialises the user's vault pages (excluding the
* Brain machinery root and the standard ignored dirs) into a stable,
* sorted `graph.json`: one node per page with its wikilinks and typed
* relations. Re-export is byte-identical (everything sorted, no
* timestamps), so the format is a deterministic interchange artifact.
*
* The importer (`importVaultGraph`, Feature 5 Task 4) reconstructs page
* stubs under three conflict modes. It refuses a node per entry rather
* than aborting the run: an unreadable shape, a path that escapes the
* vault, and a node whose path or title carries the redactor's
* placeholder all land in `rejected` while the rest of the graph imports.
* See {@link hasRedactedIdentity} for why a lost name is a refusal and not
* a lossy import.
*/
import { existsSync, mkdirSync } from "node:fs";
import { dirname, join, posix, relative } from "node:path";
import {
EXCLUDED_DIRS,
extractWikilinks,
listVaultPages,
parseFrontmatter,
writeFrontmatterAtomic,
} from "../../vault.ts";
import type { FrontmatterMap } from "../../types.ts";
import {
extractFrontmatterRelations,
normalizeRelationTarget,
} from "../../graph/frontmatter-relations.ts";
import { REDACTION_PLACEHOLDER } from "../../redactor.ts";
import { BRAIN_ROOT_REL, ensureInsideVault, isUnderBrainRoot } from "../paths.ts";
import { realVaultRelative } from "../../path-safety.ts";
import { loadVaultMap, resolveTokens } from "./role-tokens.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
export const GRAPH_VERSION = "1";
/** Typed-relation frontmatter fields (v0.19.0) carried in the graph. */
export const RELATION_FIELDS = ["related", "extends", "contradicts", "superseded_by"] as const;
export interface VaultGraphNode {
/** Obsidian basename id (wikilink target). */
readonly id: string;
/** Vault-relative POSIX path. */
readonly path: string;
readonly title: string;
/** Sorted, de-duplicated wikilink targets in the body. */
readonly links: ReadonlyArray<string>;
/** Typed relations -> sorted target lists (only non-empty fields present). */
readonly relations: Readonly<Record<string, ReadonlyArray<string>>>;
}
export interface VaultGraph {
readonly version: string;
readonly nodes: ReadonlyArray<VaultGraphNode>;
}
function stem(path: string): string {
const base = path.split(/[\\/]/).pop() ?? path;
return base.replace(/\.md$/i, "");
}
function sortedUnique(values: Iterable<string>): string[] {
return [...new Set([...values].filter((v) => v.length > 0))].toSorted();
}
function collectRelations(meta: FrontmatterMap): Record<string, ReadonlyArray<string>> {
const grouped = new Map<string, string[]>();
for (const edge of extractFrontmatterRelations(meta)) {
const arr = grouped.get(edge.relation);
if (arr) arr.push(edge.target);
else grouped.set(edge.relation, [edge.target]);
}
const out: Record<string, ReadonlyArray<string>> = {};
for (const [relation, targets] of grouped) out[relation] = sortedUnique(targets);
return out;
}
/**
* Export every user vault page (Brain machinery excluded) as a stable,
* sorted graph. Pure and read-only.
*/
export function exportVaultGraph(vault: string): VaultGraph {
const pages = listVaultPages(vault, {
skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL],
reach: MAINTENANCE_LANE_REACH,
});
const nodes: VaultGraphNode[] = [];
for (const page of pages) {
let body: string;
let meta: FrontmatterMap;
try {
const [m, b] = parseFrontmatter(page.path);
meta = m;
body = b;
} catch {
continue;
}
const links = sortedUnique(
extractWikilinks(body)
.map((t) => normalizeRelationTarget(t))
.filter((t): t is string => t !== null),
);
nodes.push({
id: stem(page.path),
path: relative(vault, page.path).split(/[\\/]/).join(posix.sep),
title: page.title,
links,
relations: collectRelations(meta),
});
}
nodes.sort((a, b) =>
a.id < b.id ? -1 : a.id > b.id ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
);
return { version: GRAPH_VERSION, nodes };
}
// ----- Import --------------------------------------------------------------
export type GraphImportMode = "skip" | "overwrite" | "merge";
export interface GraphImportResult {
readonly created: string[];
readonly skipped: string[];
readonly overwritten: string[];
readonly merged: string[];
/**
* Node paths the importer refused: a node whose shape is not readable,
* one whose path escapes the vault, and one whose path or title carries
* the redactor's placeholder (see {@link hasRedactedIdentity}).
*/
readonly rejected: string[];
}
/** Shape the importer reads from a graph node (loosely typed for JSON input). */
interface GraphNodeInput {
readonly path: string;
readonly title?: string;
readonly links?: ReadonlyArray<string>;
readonly relations?: Readonly<Record<string, ReadonlyArray<string>>>;
}
const isStringArray = (v: unknown): boolean =>
Array.isArray(v) && v.every((item) => typeof item === "string");
/**
* Runtime guard for one untrusted JSON node. `path` must be a string;
* `title` (when present) a string; `links` a string array; `relations`
* a plain object whose every value is a string array. Anything else is
* rejected so the import skips it rather than throwing mid-run.
*/
function isValidGraphNode(node: unknown): node is GraphNodeInput {
if (!node || typeof node !== "object") return false;
const n = node as Record<string, unknown>;
if (typeof n["path"] !== "string") return false;
if (n["title"] !== undefined && typeof n["title"] !== "string") return false;
if (n["links"] !== undefined && !isStringArray(n["links"])) return false;
if (n["relations"] !== undefined) {
const rel = n["relations"];
if (!rel || typeof rel !== "object" || Array.isArray(rel)) return false;
if (!Object.values(rel).every((targets) => isStringArray(targets))) return false;
}
return true;
}
/**
* Whether a node lost the identity that names it.
*
* A graph node is addressed by its `path` and displayed by its `title`,
* and {@link REDACTION_PLACEHOLDER} is a single constant: two nodes
* redacted in the same field are not two anonymous pages, they are one
* path, and importing both writes the second over the first while
* reporting two creations. The page a redacted path names cannot be
* recovered from the bundle, so the node is refused.
*
* `links` and `relations` are deliberately NOT checked: those name OTHER
* pages. A target that no longer resolves is a dangling wikilink, which is
* the vault's ordinary state and what the stub-scaffolding verb is for -
* losing a reference is not losing this node's identity.
*/
function hasRedactedIdentity(node: GraphNodeInput): boolean {
if (node.path.includes(REDACTION_PLACEHOLDER)) return true;
return node.title !== undefined && node.title.includes(REDACTION_PLACEHOLDER);
}
/**
* Render a deterministic page stub. Single-target relations land in
* frontmatter (the only form OSB's frontmatter parser round-trips);
* body wikilinks list the links. Multi-target relations are flattened
* into the body links (type not preserved - a documented limitation of
* the frontmatter parser).
*
* Exported for `notes/scaffold-stub.ts` (B3), which materialises a note
* for a dangling wikilink target. That verb needs exactly this shape and
* for exactly this reason: every byte it emits is DERIVED - the title
* from the target the link spelled, the body links from the documents the
* index says referenced it - so a scaffolded note contains no prose
* pretending to be the user's.
*/
export function renderStub(
title: string,
links: ReadonlyArray<string>,
relations: Readonly<Record<string, ReadonlyArray<string>>>,
): [FrontmatterMap, string] {
const meta: FrontmatterMap = { title };
const bodyTargets = new Set(links);
for (const [relation, targets] of Object.entries(relations)) {
if (targets.length === 1) meta[relation] = `[[${targets[0]}]]`;
else for (const t of targets) bodyTargets.add(t);
}
const sorted = [...bodyTargets].filter((t) => t.length > 0).toSorted();
const body = sorted.length > 0 ? sorted.map((t) => `- [[${t}]]`).join("\n") + "\n" : "";
return [meta, body];
}
function readExisting(path: string): { links: string[]; relations: Record<string, string[]> } {
const [meta, body] = parseFrontmatter(path);
const links = extractWikilinks(body)
.map((t) => normalizeRelationTarget(t))
.filter((t): t is string => t !== null);
const relations: Record<string, string[]> = {};
for (const edge of extractFrontmatterRelations(meta)) {
(relations[edge.relation] ??= []).push(edge.target);
}
return { links, relations };
}
/**
* Reconstruct vault page stubs from a graph under one conflict mode.
* `skip` (default) never overwrites and is idempotent; `overwrite`
* replaces; `merge` unions wikilinks + relations with the existing page.
* Every write is guarded by {@link ensureInsideVault}.
*/
export function importVaultGraph(
vault: string,
// Untrusted input (JSON from a graph.json or a bank bundle); every node
// is shape-guarded per entry below, so the element type is `unknown`
// rather than a structural promise the runtime does not enforce.
graph: { nodes?: ReadonlyArray<unknown> },
opts: { mode?: GraphImportMode } = {},
): GraphImportResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
const mode: GraphImportMode = opts.mode ?? "skip";
const result: GraphImportResult = {
created: [],
skipped: [],
overwritten: [],
merged: [],
rejected: [],
};
const vaultMap = loadVaultMap(vault);
// Guard the container shape: a non-array `nodes` (string, object, scalar)
// from untrusted JSON would otherwise throw or mis-iterate. Per-entry
// validation below still rejects each malformed element.
const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
for (const node of nodes) {
// Validate the node shape per entry: a single malformed JSON node is
// rejected and the import continues, instead of throwing and aborting
// the whole run. `graph` arrives from untrusted JSON, so the static
// GraphNodeInput type is not a runtime guarantee.
if (!isValidGraphNode(node)) {
result.rejected.push(String((node as { path?: unknown })?.path ?? "<invalid-node>"));
continue;
}
// A node whose own name was redacted before it reached this bundle.
// The export boundary refuses to emit one; a bundle written by an
// earlier build, or scrubbed by another tool, can still carry it.
if (hasRedactedIdentity(node)) {
result.rejected.push(node.path);
continue;
}
// Resolve `{{role}}` tokens in the target path via the vault-map so a
// portable graph can address user folders abstractly (v0.22.0).
const relPath = resolveTokens(vaultMap, node.path);
// The `Brain/` machinery root is not addressable from an untrusted
// graph bundle, in any mode. `skip` would still CREATE a missing
// target and `overwrite` rewrites existing files, so without this
// refusal a bundle could plant or replace standing rules, vault
// identity, or the write binding's own config - the same wall the
// note-target envelope applies to every caller-named note write.
//
// The wall reads the path the way the filesystem will: separators
// normalized (`\` is one on Windows), `.`/`..` collapsed
// (`./Brain/x`, `x/../Brain/x`), and the Brain segment compared
// case-insensitively (`brain/x` opens `Brain/` on macOS and
// Windows). A second read after containment checks where the bytes
// actually land, so a vault folder that is a symlink into `Brain/`
// does not carry the write past the lexical check.
if (isUnderBrainRoot(relPath)) {
result.rejected.push(node.path);
continue;
}
let path: string;
try {
path = ensureInsideVault(join(vault, relPath), vault);
} catch {
result.rejected.push(node.path);
continue;
}
// A landing path that cannot be resolved (a note used as a folder, a
// link loop, an unreadable folder) is rejected like any other bad
// node rather than aborting the rest of the import.
let landsAt: string | null;
try {
landsAt = realVaultRelative(vault, relative(vault, path));
} catch {
landsAt = null;
}
if (landsAt === null || isUnderBrainRoot(landsAt)) {
result.rejected.push(node.path);
continue;
}
const title = node.title ?? node.path;
const incomingLinks = node.links ?? [];
const incomingRelations = node.relations ?? {};
const exists = existsSync(path);
if (exists && mode === "skip") {
result.skipped.push(node.path);
continue;
}
let links: ReadonlyArray<string> = incomingLinks;
let relations: Record<string, ReadonlyArray<string>> = { ...incomingRelations };
if (exists && mode === "merge") {
const prev = readExisting(path);
links = [...new Set([...prev.links, ...incomingLinks])];
const merged: Record<string, string[]> = {};
for (const [rel, targets] of Object.entries(prev.relations)) merged[rel] = [...targets];
for (const [rel, targets] of Object.entries(incomingRelations)) {
merged[rel] = [...new Set([...(merged[rel] ?? []), ...targets])];
}
relations = merged;
}
const [meta, body] = renderStub(title, links, relations);
mkdirSync(dirname(path), { recursive: true });
writeFrontmatterAtomic(path, meta, body, { overwrite: true, vaultForRelativePath: vault });
if (!exists) result.created.push(node.path);
else if (mode === "merge") result.merged.push(node.path);
else result.overwritten.push(node.path);
}
return result;
}