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 render pass without a manual command (design D7): the end of every
* dream pass and the session-start hook run it, so the view writer keeps
* the view current and doctor does not report it silent.
*
* The same trigger first runs the automatic transition import of a
* switched machine (`store-migration/auto-transition.ts`).
*
* Rules:
*
* - **Only where the store is in use.** No store at the resolved root,
* or no device id configured (none is ever minted here), means nothing
* runs and `null` is returned, so a machine that never opted in pays one
* `stat` and its dream summary is unchanged.
* - **Cheap off the writer.** The pass reads the writer records first and
* stops there on any other machine (`render.ts`).
* - **Throttled from hooks.** The session-start trigger runs at most once
* an hour per device; the stamp is written before the pass, so a pass
* that dies does not retry at every session start.
* - **Bounded.** A trigger may pass a time budget; the pass stops between
* pages once it runs out, and the rest wait for the next pass.
* - **Fail open.** Every failure is returned as `{ status: "error" }`,
* never thrown: a dream pass or a session start must not fail because
* the view could not be rendered.
*/
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { readDeviceId, resolveAgentName, resolveVault } from "../config.ts";
import { readVaultIdentity } from "../brain/vault-identity.ts";
import { inspectStore, openStore, type StoreHandle } from "../store/store-open.ts";
import { runAutoTransition } from "../store-migration/auto-transition.ts";
import { deviceStateDirFor, resolveConfiguredStoreRoot } from "../store/store-paths.ts";
import {
DEVICE_HOOK_AUDIT_DIR,
VIEW_AUTO_PASS_FILE,
VIEW_AUTO_PASS_INTERVAL_MS,
VIEW_STATE_DIR,
} from "./constants.ts";
import { runViewPass, type ViewPassReport } from "./render.ts";
import { resolveViewTarget } from "./target.ts";
/** What started the pass. */
export type AutoViewTrigger = "dream" | "session-start";
export interface AutoViewOptions {
readonly trigger: AutoViewTrigger;
readonly configPath?: string;
/** Wall clock (default `Date.now`). */
readonly now?: () => number;
/** Stop between pages once this many milliseconds have passed. */
readonly budgetMs?: number;
}
export type AutoViewResult =
| ViewPassReport
| { readonly status: "throttled" }
| { readonly status: "error"; readonly error: string };
function autoPassPath(store: StoreHandle): string {
return join(store.deviceStateDir, VIEW_STATE_DIR, VIEW_AUTO_PASS_FILE);
}
/** Whether the hourly hook pass ran recently; records this one when not. */
function throttled(store: StoreHandle, nowMs: number): boolean {
const path = autoPassPath(store);
try {
const last = (JSON.parse(readFileSync(path, "utf8")) as { at?: unknown }).at;
if (
typeof last === "number" &&
nowMs - last >= 0 &&
nowMs - last < VIEW_AUTO_PASS_INTERVAL_MS
) {
return true;
}
} catch {
// never ran, or unreadable: run now
}
mkdirSync(join(store.deviceStateDir, VIEW_STATE_DIR), { recursive: true });
writeFileSync(path, `${JSON.stringify({ at: nowMs })}\n`);
return false;
}
/** The opened store, or `null` when this machine does not use one. */
function storeInUse(configPath: string | undefined): StoreHandle | null {
const { root } = resolveConfiguredStoreRoot(configPath);
if (inspectStore(root) === null) return null;
const device = readDeviceId(configPath);
if (device === null) return null;
return openStore({ root, device });
}
/** One render pass for `options.trigger`; `null` when the store is not in use here. */
export function runAutoViewPass(options: AutoViewOptions): AutoViewResult | null {
const now = options.now ?? Date.now;
try {
const store = storeInUse(options.configPath);
if (store === null) return null;
if (options.trigger === "session-start" && throttled(store, now())) {
return { status: "throttled" };
}
// The budget runs from the start of the pass, the transition import
// below included: the whole pass is synchronous, so nothing else can
// stop it inside the hook's ceiling. Measured on the pass's own clock.
const started = now();
const vault = resolveVault(options.configPath);
const agent = resolveAgentName(options.configPath);
// A switched machine first imports late legacy writes of machines still
// on an old release (task 2.4), so the view renders them too. It has
// its own hourly throttle and never fails the render.
runAutoTransition({
store,
vault,
agent,
vaultId: vault === null ? null : (readVaultIdentity(vault)?.vault_id ?? null),
trigger: options.trigger,
...(options.now !== undefined ? { now: options.now } : {}),
});
const target = resolveViewTarget(store.root, options.configPath, vault);
const budget = options.budgetMs;
return runViewPass(store, {
target: target?.dir ?? null,
vault,
agent,
...(options.now !== undefined ? { now: options.now } : {}),
...(budget !== undefined ? { shouldStop: () => now() - started > budget } : {}),
});
} catch (err) {
return { status: "error", error: err instanceof Error ? err.message : String(err) };
}
}
/**
* The device-local hook audit of this machine's store
* (`<device state>/hook-audit`, design D14 item 1), or `null` when no
* store is in use here. Never synced.
*/
export function deviceHookAuditDir(configPath?: string): string | null {
try {
const store = inspectStore(resolveConfiguredStoreRoot(configPath).root);
return store === null ? null : join(deviceStateDirFor(store.storeId), DEVICE_HOOK_AUDIT_DIR);
} catch {
return null;
}
}
/** One line for a report: what the pass did, naming the writer when this is not it. */
export function describeAutoView(result: AutoViewResult): string {
switch (result.status) {
case "not-writer":
return `this machine writes no view page; the view writer is ${result.writer}`;
case "rendered": {
const written = result.pages.filter((p) => p.status === "written").length;
const deferred = result.pages.filter((p) => p.status === "deferred").length;
const removed = result.pages.filter((p) => p.status === "removed").length;
return (
`rendered ${result.pages.length - removed} page(s), ${written} changed` +
(removed > 0 ? `, ${removed} removed` : "") +
(deferred > 0 ? `, ${deferred} deferred to the next pass` : "")
);
}
case "released":
return `handed the view writer role to ${result.to}`;
case "error":
return `the view could not be rendered: ${result.error}`;
case "incomplete-read":
return "the view was not rendered: some shards could not be read";
case "no-writer":
return "no machine renders the view yet";
case "waiting-for-claim":
return "this machine just took the view writer role; it renders from its next pass";
case "no-target":
return "no view folder is configured";
case "throttled":
return "the view was rendered less than an hour ago";
}
}
/**
* The audit line of a pass worth one: `ok` only for a rendered pass whose
* pages were all written, unchanged or deferred by the budget; the pages
* that were not written with their reason, and the unreadable shards of an
* incomplete read, so the line says what to fix.
*/
export function autoViewAudit(result: AutoViewResult): [boolean, Record<string, unknown>] {
const failed =
result.status === "rendered"
? result.pages
.filter(
(p) => p.status !== "written" && p.status !== "unchanged" && p.status !== "removed",
)
.map((p) => ({
page: p.page,
status: p.status,
...(p.detail ? { detail: p.detail } : {}),
}))
: [];
const ok = result.status === "rendered" && failed.every((p) => p.status === "deferred");
return [
ok,
{
status: result.status,
summary: describeAutoView(result),
...(failed.length > 0 ? { pages: failed } : {}),
...(result.status === "incomplete-read" ? { shards: result.shards } : {}),
...(result.status === "error" ? { error: result.error } : {}),
},
];
}