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
/**
* Pages that leave the view (task 3.2, design D16 item 10): a topic
* renamed, merged or undone, a report removed, or a topic folder another
* topic now takes. Split from `render.ts`, which calls it before it
* renders the pages of a pass.
*
* Two kinds of page leave:
*
* - a page of a retiring folder (`topics/`, `reports/`, `sources/`) a
* render record names and the store no longer renders;
* - a page the store still renders whose file on disk names another
* topic in its id line: the folder slot passed from one topic to
* another (a rename, or a topic with an earlier clock that synced in
* late), so the old topic's page and the user's files in its folder
* belong elsewhere now.
*
* Either way an edit the page carries, and every conflict copy of it, is
* ingested first, as before a render; the page leaves its name by one
* atomic rename, so an edit that lands right before it is captured too;
* and the user's companion files of a topic folder follow the topic to
* its current folder. A topic page whose file is already gone (a pass
* that died after removing it) still has its companions moved, by the
* topic its last render record names.
*
* Every page path comes from store records any device can write, so it
* passes the exact shape check and the inside-the-view check of
* `page-path.ts` before any file operation; any other path is ignored.
*/
import { statSync } from "node:fs";
import { basename, dirname } from "node:path";
import { compareCodeUnits } from "../store/compare.ts";
import type { StoreHandle } from "../store/store-open.ts";
import type { ViewCatchUp } from "./catch-up.ts";
import {
VIEW_RENDER_KIND,
VIEW_RETIRING_DIRS,
VIEW_TOPIC_ARCHIVE_PAGE,
VIEW_TOPIC_PAGE,
} from "./constants.ts";
import { pageLines } from "./corrections.ts";
import { pageFileInside, retiringPageFile } from "./page-path.ts";
import {
capturePage,
conflictCopies,
listCompanions,
moveCompanions,
NotAPageFileError,
readPage,
removeEmptyFolder,
} from "./page-io.ts";
import type { PageStats } from "./page-stats.ts";
import type { PageModel } from "./pages.ts";
import { topicOfIdLine } from "./topic-pages.ts";
import {
bytesSum,
lastRender,
loadBase,
ownSums,
type RenderBase,
type ReplacedReason,
} from "./view-records.ts";
/** What retiring needs from the render pass it runs in. */
export interface RetireContext {
readonly store: StoreHandle;
/** The pass's current read (an ingest replaces it). */
read(): ViewCatchUp;
/** The pages the store renders now (rebuilt after an ingest). */
models(): ReadonlyMap<string, PageModel>;
readonly stats: PageStats;
/** Store a version that is not the writer's own render; returns the records written. */
ingest(page: string, base: RenderBase | null, text: string, reason: ReplacedReason): number;
}
/** What happened to one page that left. */
export interface RetireReport {
readonly page: string;
readonly status: "removed" | "base-pending" | "deferred";
readonly ingested: number;
readonly detail?: string;
}
const COMPANION_SKIP: ReadonlySet<string> = new Set([VIEW_TOPIC_PAGE, VIEW_TOPIC_ARCHIVE_PAGE]);
function hasContent(bytes: Buffer | null): bytes is Buffer {
return bytes !== null && pageLines(bytes.toString("utf8")).some((l) => l.trim() !== "");
}
const archiveFirst = (page: string): number => (basename(page) === VIEW_TOPIC_ARCHIVE_PAGE ? 0 : 1);
function byFolder(a: string, b: string): number {
return compareCodeUnits(dirname(a), dirname(b)) || archiveFirst(a) - archiveFirst(b);
}
/** The folder a topic's page lives in now, from the models of this pass. */
function currentTopicFolder(ctx: RetireContext, topic: string | null): string | null {
if (topic === null) return null;
for (const model of ctx.models().values()) {
if (model.topic === topic && basename(model.page) === VIEW_TOPIC_PAGE)
return dirname(model.page);
}
return null;
}
/** The topic the last render record of `page` names, or `null`. */
function renderedTopic(ctx: RetireContext, page: string): string | null {
const topic = lastRender(ctx.read(), page)?.record.body["topic"];
return typeof topic === "string" ? topic : null;
}
function moveFolderCompanions(
ctx: RetireContext,
target: string,
page: string,
topic: string | null,
only?: ReadonlySet<string>,
): void {
const moved = currentTopicFolder(ctx, topic);
if (moved === null || moved === dirname(page)) return;
const to = pageFileInside(target, `${moved}/${VIEW_TOPIC_PAGE}`);
const from = pageFileInside(target, page);
if (to === null || from === null) return;
moveCompanions(dirname(from), dirname(to), COMPANION_SKIP, only);
}
/**
* The companion names in the folder of each page, read before anything
* moves: when topics exchange folders, a folder receives another topic's
* files before its own leave, and only the names it held at the start
* are its topic's.
*/
function companionsAtStart(target: string, pages: ReadonlyArray<string>): Map<string, Set<string>> {
const out = new Map<string, Set<string>>();
for (const page of pages) {
const path = pageFileInside(target, page);
if (path !== null) out.set(page, new Set(listCompanions(dirname(path), COMPANION_SKIP)));
}
return out;
}
/** Take one page out of the view; `null` when there was nothing to take. */
function retireOne(
ctx: RetireContext,
target: string,
page: string,
path: string,
options: { readonly keepFolder: boolean; readonly companions?: ReadonlySet<string> },
): RetireReport | null {
const copies = conflictCopies(path);
if (readPage(path) === null && copies.length === 0) {
// The page went before its companions did (a pass that died between).
if (basename(page) === VIEW_TOPIC_PAGE) {
moveFolderCompanions(ctx, target, page, renderedTopic(ctx, page), options.companions);
if (!options.keepFolder) removeEmptyFolder(dirname(path));
}
return null;
}
const last = lastRender(ctx.read(), page);
const base = last === null ? null : loadBase(ctx.store, last);
if (last !== null && base === null) {
return { page, status: "base-pending", ingested: 0, detail: "the merge base has not synced" };
}
const own = ownSums(ctx.read(), page);
let ingested = 0;
for (const copy of copies) {
// A name that is not a regular file (a folder, a link) is refused
// where it is. A copy is taken out of its name before it is read, as
// the page is: one a sync tool writes again meanwhile is left for the
// next pass, never removed.
readPage(copy);
const captured = capturePage(copy);
if (captured === null) continue;
try {
if (hasContent(captured.bytes) && !own.has(bytesSum(captured.bytes))) {
ingested += ctx.ingest(page, base, captured.bytes.toString("utf8"), "conflict-copy");
}
} catch (err) {
captured.restore();
throw err;
}
captured.discard();
}
const captured = capturePage(path);
if (captured !== null) {
try {
if (hasContent(captured.bytes) && !own.has(bytesSum(captured.bytes))) {
const text = captured.bytes.toString("utf8");
ingested += ctx.ingest(page, base, text, base ? "edit" : "foreign");
}
} catch (err) {
captured.restore();
throw err;
}
captured.discard();
if (basename(page) === VIEW_TOPIC_PAGE) {
const firstLine = pageLines(captured.bytes.toString("utf8"))[0] ?? "";
// The writer's own render record says whose page it was; the id line,
// which a user can edit, decides only when that record names none.
const owner = renderedTopic(ctx, page) ?? topicOfIdLine(firstLine);
moveFolderCompanions(ctx, target, page, owner, options.companions);
}
}
if (!options.keepFolder) removeEmptyFolder(dirname(path));
ctx.stats.delete(page);
return { page, status: "removed", ingested };
}
/**
* The topic the id line of the page file at `path` names, or `null`. A
* name that is not a regular file (a folder, a link) names no owner: the
* render of that page reports it as refused, and the rest of the pass goes on.
*/
function ownerOnDisk(path: string): string | null {
let disk: Buffer | null;
try {
disk = readPage(path);
} catch (err) {
if (err instanceof NotAPageFileError) return null;
throw err;
}
return disk === null ? null : topicOfIdLine(pageLines(disk.toString("utf8"))[0] ?? "");
}
/**
* Live topic pages whose file is another topic's: the slot passed to a new
* topic. Whose a page is comes from the writer's own last render record of
* it; the id line on disk, which a user's edit or a sync merge can change,
* decides only for a page rendered before render records named a topic.
*/
function foreignPages(ctx: RetireContext, target: string): string[] {
const out: string[] = [];
for (const model of ctx.models().values()) {
if (model.topic === undefined) continue;
const path = pageFileInside(target, model.page);
if (path === null) continue;
// A page already gone still names, in its last render record, whose
// folder this was: that topic's files must still leave it. The disk
// is read only when no render record says it.
const owner = renderedTopic(ctx, model.page) ?? ownerOnDisk(path);
if (owner !== null && owner !== model.topic) out.push(model.page);
}
return out.toSorted(byFolder);
}
/** Whether `a` and `b` are one file on disk (a case-insensitive file system, or a link). */
function sameFile(a: string, b: string): boolean {
try {
const sa = statSync(a);
const sb = statSync(b);
return sa.dev === sb.dev && sa.ino === sb.ino;
} catch {
return false;
}
}
/** Pages a render record names in a retiring folder that the store no longer renders. */
function retiredPages(ctx: RetireContext, target: string): string[] {
const live = ctx.models();
const livePaths = new Map<string, string>();
for (const page of live.keys()) {
const file = pageFileInside(target, page);
if (file !== null) livePaths.set(page.toLowerCase(), file);
}
const out = new Set<string>();
for (const records of ctx.read().records.values()) {
for (const record of records) {
const page = record.body["page"];
if (record.kind !== VIEW_RENDER_KIND || typeof page !== "string" || live.has(page)) continue;
if (!VIEW_RETIRING_DIRS.some((dir) => page.startsWith(`${dir}/`))) continue;
const file = retiringPageFile(target, page);
if (file === null) continue;
// On a case-insensitive file system a page whose path differs from a
// live page's only in case is that live page's file: never retired.
const twin = livePaths.get(page.toLowerCase());
if (twin !== undefined && sameFile(file, twin)) continue;
out.add(page);
}
}
return [...out].toSorted(byFolder);
}
/**
* Retire every page that left the view, in the order that keeps a
* user's files with the right topic: first the pages whose folder slot
* another topic took (their companions move out before anything moves
* in), then the pages no longer rendered. `onFailure` turns an error of
* one page into its report; the other pages still retire.
*/
export function retirePages<R>(
ctx: RetireContext,
target: string,
onFailure: (page: string, err: unknown) => R,
shouldStop?: () => boolean,
): Array<RetireReport | R> {
const reports: Array<RetireReport | R> = [];
const foreign = foreignPages(ctx, target);
const companions = companionsAtStart(target, foreign);
const run = (page: string, keepFolder: boolean): void => {
const path = keepFolder ? pageFileInside(target, page) : retiringPageFile(target, page);
if (path === null) return;
// The pass's time budget holds here too: the rest wait for a later pass.
if (shouldStop?.() === true) {
reports.push({ page, status: "deferred", ingested: 0, detail: "the time budget ran out" });
return;
}
try {
const own = companions.get(page);
const report = retireOne(ctx, target, page, path, {
keepFolder,
...(own !== undefined ? { companions: own } : {}),
});
if (report !== null) reports.push(report);
} catch (err) {
reports.push(onFailure(page, err));
}
};
for (const page of foreign) run(page, true);
for (const page of retiredPages(ctx, target)) run(page, false);
return reports;
}