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
/**
* Moving this machine's device-local surfaces into its device-local state
* (design D11 "Later machines", D14 item 6): every surface the map sends
* to `device-local` or `backup` is copied, file by file and verified by
* hash, into `<device state>/migration/local/<vault-relative path>`, where
* the store-only mode reads it. A backup-class surface (secrets, signing
* keys, checkpoints, lockfiles) lives there after the switch as well as in
* the verified backup. A rebuildable surface (the search index and the
* caches) is not copied: the switched machine rebuilds it in its own place. The originals stay in the legacy tree, which
* leaves the vault only through the removal step (task 2.5) and is
* archived then, never deleted.
*/
import { createHash } from "node:crypto";
import { copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
import { dirname, join, relative, resolve, sep } from "node:path";
import type { CatalogueEntry } from "./catalogue.ts";
import { DESTINATION_KIND } from "./destinations.ts";
import { MIGRATION_LOCAL_DIR as LOCAL_DIR } from "./device-state-layout.ts";
import { copyOwnerOnly, ensureOwnerOnlyRoot } from "./owner-only-copy.ts";
import { realpathInsideVault } from "../path-safety.ts";
import { SWITCHED_SKILLS_DIR } from "../surface/skills-dir.ts";
function filesBelow(path: string): string[] {
let stat;
try {
stat = lstatSync(path);
} catch {
return [];
}
if (stat.isFile()) return [path];
if (!stat.isDirectory()) return [];
return readdirSync(path)
.toSorted()
.flatMap((name) => filesBelow(join(path, name)));
}
const sha256 = (path: string): string =>
createHash("sha256").update(readFileSync(path)).digest("hex");
/** A copy that did not verify. */
export class LocalStateMoveError extends Error {
override readonly name = "LocalStateMoveError";
}
/**
* Copy every device-local and backup-class surface of `vault`, except the
* rebuildable ones, into `migrationDir/local`.
* Returns the vault-relative paths copied; throws {@link LocalStateMoveError}
* when a copy does not match its original.
*/
export function moveDeviceLocalState(
vault: string,
catalogue: ReadonlyArray<CatalogueEntry>,
migrationDir: string,
): string[] {
const copied: string[] = [];
const root = join(migrationDir, LOCAL_DIR);
let rootReady = false;
for (const entry of catalogue) {
const to = entry.mapping.destination.to;
if (to !== DESTINATION_KIND.deviceLocal && to !== DESTINATION_KIND.backup) continue;
if (entry.mapping.rebuildable === true) continue;
for (const locator of entry.locators) {
if (locator.shape !== "tree") continue;
// A device-local locator with a grammar names rows, not files to copy;
// a backup-class one is copied whole, as the backup copies it.
if (to === DESTINATION_KIND.deviceLocal && locator.grammar !== undefined) continue;
for (const file of filesBelow(locator.path)) {
const rel = relative(vault, file).split(sep).join("/");
const target = join(root, ...rel.split("/"));
// Secrets and signing keys among them: owner-only whatever mode
// the source had (`owner-only-copy.ts`).
if (!rootReady) ensureOwnerOnlyRoot(root);
rootReady = true;
copyOwnerOnly(file, target, root);
if (sha256(target) !== sha256(file)) {
throw new LocalStateMoveError(`the device-local copy of ${rel} does not match it`);
}
copied.push(rel);
}
}
}
return copied;
}
/** What {@link placeVaultFiles} did with each legacy file. */
export interface VaultFilesPlacement {
/** Vault-relative paths written to their switched location. */
readonly placed: ReadonlyArray<string>;
/** Vault-relative paths left alone: the switched location already held a different file. */
readonly kept: ReadonlyArray<string>;
}
/** Whether `target` or a folder between `vault` and it is a symbolic link (or junction). */
function linkBelowVault(target: string, vault: string): boolean {
const root = resolve(vault);
for (let path = resolve(target); path !== root; path = dirname(path)) {
try {
if (lstatSync(path).isSymbolicLink()) return true;
} catch {
// Not there yet: nothing to follow.
}
if (dirname(path) === path) return false;
}
return false;
}
/**
* Copy every surface the map sends to `vault-files` (accepted skills) from
* the legacy tree to its place in the user's vault, outside `Brain/`:
* `Brain/skills/<rest>` lands at `<vault>/skills/<rest>`, verified by hash.
* A file already there with the same bytes counts as placed; one with
* different bytes is kept as the user's and named. The originals stay in
* the legacy tree, which leaves the vault only through the removal step.
*/
export function placeVaultFiles(
vault: string,
catalogue: ReadonlyArray<CatalogueEntry>,
): VaultFilesPlacement {
const placed: string[] = [];
const kept: string[] = [];
for (const entry of catalogue) {
if (entry.mapping.destination.to !== DESTINATION_KIND.vaultFiles) continue;
for (const locator of entry.locators) {
if (locator.shape !== "tree") continue;
for (const file of filesBelow(locator.path)) {
const inLane = relative(locator.path, file);
const target = join(vault, SWITCHED_SKILLS_DIR, inLane);
const rel = relative(vault, file).split(sep).join("/");
let present = false;
try {
present = lstatSync(target).isFile();
} catch {
present = false;
}
if (present) {
(sha256(target) === sha256(file) ? placed : kept).push(rel);
continue;
}
// Vault content syncs, so a link planted at `skills/` or below it
// must not carry these writes out of the vault. A dangling link
// slips past the real-path walk (it "does not exist"), so every
// entry between the vault and the target is checked for a link too.
if (linkBelowVault(target, vault) || !realpathInsideVault(target, vault)) {
throw new LocalStateMoveError(
`the vault place of ${rel} leads out of the vault by a link`,
);
}
mkdirSync(dirname(target), { recursive: true });
copyFileSync(file, target);
if (sha256(target) !== sha256(file)) {
throw new LocalStateMoveError(`the vault copy of ${rel} does not match it`);
}
placed.push(rel);
}
}
}
return { placed, kept };
}