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
import { mkdirSync, readFileSync } from "node:fs";
import { basename, dirname, join } from "node:path";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import { ensureInsideVault } from "../path-safety.ts";
import {
proceduralGraphPath,
proceduralMemoryIndexPath,
skillProposalAcceptedPath,
skillProposalPendingPath,
skillProposalRejectedPath,
} from "./paths.ts";
import type { ProceduralMemoryEntry } from "./types.ts";
import {
assertLaneWrite,
readLaneFile,
lanePageExists,
listLaneFiles,
parseLanePage,
lanePagesInStore,
readLaneText,
} from "../store/lane-pages.ts";
import { BRAIN_PROCEDURAL_MEMORY_REL } from "./path-constants.ts";
export type ProceduralGraphNodeKind = "procedure" | "skill" | "runbook" | "proposal" | "entity";
export type ProceduralGraphEdgeKind =
| "derived_from_proposal"
| "trigger_matches"
| "tag_matches"
| "source_mentions"
| "proposal_mentions";
export interface ProceduralGraphNode {
readonly id: string;
readonly kind: ProceduralGraphNodeKind;
readonly title: string;
readonly sourcePath: string | null;
readonly metadata: Readonly<Record<string, unknown>>;
}
export interface ProceduralGraphEdge {
readonly from: string;
readonly to: string;
readonly kind: ProceduralGraphEdgeKind;
}
export interface ProceduralGraphProjection {
readonly schema_version: 1;
readonly generated_at: string;
readonly nodes: ReadonlyArray<ProceduralGraphNode>;
readonly edges: ReadonlyArray<ProceduralGraphEdge>;
}
export interface ProceduralGraphBuildOptions {
readonly now?: Date;
}
export function rebuildProceduralGraph(
vault: string,
opts: ProceduralGraphBuildOptions = {},
): ProceduralGraphProjection {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const now = opts.now ?? new Date();
const nodes: ProceduralGraphNode[] = [];
const edges: ProceduralGraphEdge[] = [];
const entries = readProceduralIndex(vault);
const nodeById = new Set<string>();
for (const entry of entries) {
const node: ProceduralGraphNode = {
id: entry.id,
kind: entry.kind,
title: entry.title,
sourcePath: entry.sourcePath,
metadata: {
triggers: [...entry.triggers],
tags: [...entry.tags],
source: entry.source,
version: entry.version,
},
};
nodes.push(node);
nodeById.add(node.id);
if (entry.kind === "procedure") {
const proposalId = detectProcedureSourceProposal(vault, entry.sourcePath);
if (proposalId) {
edges.push({
from: node.id,
to: proposalId,
kind: "derived_from_proposal",
});
}
}
for (const trigger of entry.triggers) {
const entityId = entityNodeId(`trigger:${trigger}`);
ensureEntityNode(nodes, nodeById, entityId, `Trigger: ${trigger}`);
edges.push({ from: node.id, to: entityId, kind: "trigger_matches" });
}
for (const tag of entry.tags) {
const entityId = entityNodeId(`tag:${tag}`);
ensureEntityNode(nodes, nodeById, entityId, `Tag: ${tag}`);
edges.push({ from: node.id, to: entityId, kind: "tag_matches" });
}
for (const token of sourcePathTokens(entry.sourcePath)) {
const entityId = entityNodeId(`path:${token}`);
ensureEntityNode(nodes, nodeById, entityId, `Path: ${token}`);
edges.push({ from: node.id, to: entityId, kind: "source_mentions" });
}
}
for (const proposal of listProposals(vault)) {
nodes.push(proposal);
nodeById.add(proposal.id);
for (const token of sourcePathTokens(proposal.sourcePath ?? "")) {
const entityId = entityNodeId(`proposal-path:${token}`);
ensureEntityNode(nodes, nodeById, entityId, `Proposal Path: ${token}`);
edges.push({
from: proposal.id,
to: entityId,
kind: "proposal_mentions",
});
}
}
const projection: ProceduralGraphProjection = {
schema_version: 1,
generated_at: now.toISOString(),
nodes: Object.freeze(
nodes
.toSorted((left, right) => left.id.localeCompare(right.id))
.map((item) => Object.freeze(item)),
),
edges: Object.freeze(
dedupeEdges(edges)
.toSorted(
(left, right) =>
left.from.localeCompare(right.from) ||
left.to.localeCompare(right.to) ||
left.kind.localeCompare(right.kind),
)
.map((item) => Object.freeze(item)),
),
};
writeMachineStateText(proceduralGraphPath(vault), `${JSON.stringify(projection, null, 2)}\n`);
return projection;
}
/**
* Write a procedural projection or counter file. They are machine state
* (`paths.ts`), never store records: the graph and the hints are
* recomputed on each machine, and the counters tick on every use.
*/
export function writeMachineStateText(path: string, text: string): void {
mkdirSync(dirname(path), { recursive: true });
atomicWriteFileSync(path, text);
}
/** The text of a machine-state file, or null when there is none. */
function readMachineStateText(path: string): string | null {
try {
return readFileSync(path, "utf8");
} catch {
return null;
}
}
/**
* The text of the procedural projection or counter file at `path` (its
* machine-state location), or null when there is none.
*
* A machine switched before these files became machine state (task 3.10)
* holds them as `lane-entry` records of the store, the migration's import
* of the legacy files. Until this machine has its own copy, that record is
* read and adopted: copied into the machine-state location on the first
* read, so a switched machine answers from it before its next reconcile.
* The record itself stays in the store until the legacy tree leaves the
* vault (`store-migration/removal.ts` retires it then), so a rollback
* still finds the legacy file it was imported from.
*
* `guard` runs the adoption write: a file other writers update (the usage
* counters) passes the run of its write lock, and the copy is written only
* when the file is still absent inside it, so an adoption never lands over
* a tick another process wrote first. A caller that already holds the lock
* passes none.
*/
export function readProceduralState(
vault: string,
path: string,
guard: (write: () => void) => void = (write) => write(),
): string | null {
const own = readMachineStateText(path);
if (own !== null) return own;
if (!lanePagesInStore(vault)) return null;
const stored = join(vault, BRAIN_PROCEDURAL_MEMORY_REL, basename(path));
if (stored === path) return null;
let text: string | null;
try {
text = readLaneText(vault, stored);
} catch {
return null;
}
if (text === null) return null;
let answer = text;
try {
guard(() => {
// Another process may have adopted (and ticked) it meanwhile.
const now = readMachineStateText(path);
if (now !== null) {
answer = now;
return;
}
writeMachineStateText(path, text);
});
} catch {
// Adopted on the next read instead; the answer stands.
}
return answer;
}
export function readProceduralGraph(vault: string): ProceduralGraphProjection | null {
const text = readProceduralState(vault, proceduralGraphPath(vault));
if (text === null) return null;
try {
const parsed = JSON.parse(text) as ProceduralGraphProjection;
if (parsed.schema_version !== 1) return null;
if (!Array.isArray(parsed.nodes) || !Array.isArray(parsed.edges)) return null;
return parsed;
} catch {
return null;
}
}
function readProceduralIndex(vault: string): ProceduralMemoryEntry[] {
const path = proceduralMemoryIndexPath(vault);
if (!lanePageExists(vault, path)) return [];
try {
const parsed = JSON.parse(readLaneFile(vault, path)) as {
schema_version?: unknown;
entries?: ProceduralMemoryEntry[];
};
if (parsed.schema_version !== 1) return [];
if (!Array.isArray(parsed.entries)) return [];
return parsed.entries;
} catch {
return [];
}
}
function detectProcedureSourceProposal(vault: string, sourcePath: string): string | null {
if (!sourcePath.startsWith("Brain/procedures/")) return null;
let absPath: string;
try {
absPath = ensureInsideVault(join(vault, sourcePath), vault);
} catch {
return null;
}
if (!lanePageExists(vault, absPath)) return null;
// Unit F: `parseFrontmatter` cannot throw (it reads inside its own try;
// everything after is string work), so the `catch { return null }` that
// stood here was unreachable - and redundant, since a failed read
// yields an empty map and falls through to the same `return null`.
// Dropped lines are reported centrally; see the "Why most readers keep
// the two-tuple form" section in src/core/vault.ts.
const [fm] = parseLanePage(vault, absPath);
if (typeof fm["source_proposal"] === "string" && fm["source_proposal"].trim()) {
return fm["source_proposal"].trim();
}
return null;
}
function listProposals(vault: string): ProceduralGraphNode[] {
const out: ProceduralGraphNode[] = [];
for (const tuple of [
["pending", skillProposalPendingPath],
["accepted", skillProposalAcceptedPath],
["rejected", skillProposalRejectedPath],
] as const) {
const [status, builder] = tuple;
const dir = dirname(builder(vault, "sample"));
if (!lanePageExists(vault, dir)) continue;
for (const name of readDirSorted(vault, dir)) {
if (!name.endsWith(".md")) continue;
const absPath = join(dir, name);
// Unit F: unreachable `catch { continue }` removed - nothing in this
// body throws (`parseFrontmatter` reads inside its own try, and the
// rest is property reads and `basename`). A file whose frontmatter
// could not be read yields an empty map, fails the `kind` check on
// the next line, and is skipped exactly as the dead branch intended.
// See the "Why most readers keep the two-tuple form" section in
// src/core/vault.ts for where the condition IS reported.
const [fm] = parseLanePage(vault, absPath);
if (fm["kind"] !== "brain-skill-proposal") continue;
const id = typeof fm["id"] === "string" ? fm["id"] : `proposal-${basename(name, ".md")}`;
out.push({
id,
kind: "proposal",
title:
typeof fm["slug"] === "string"
? `Proposal: ${fm["slug"]}`
: `Proposal: ${basename(name, ".md")}`,
sourcePath: `Brain/skill-proposals/${status}/${name}`,
metadata: {
status,
pattern_kind: fm["pattern_kind"] ?? null,
},
});
}
}
return out;
}
function readDirSorted(vault: string, dir: string): string[] {
try {
return listLaneFiles(vault, dir, "").toSorted();
} catch {
return [];
}
}
function sourcePathTokens(path: string): string[] {
return path
.replaceAll("\\", "/")
.split("/")
.map((part) => part.trim().toLowerCase())
.filter((part) => part.length >= 3 && /^[a-z0-9._-]+$/.test(part));
}
function ensureEntityNode(
nodes: ProceduralGraphNode[],
nodeById: Set<string>,
id: string,
title: string,
): void {
if (nodeById.has(id)) return;
nodes.push({
id,
kind: "entity",
title,
sourcePath: null,
metadata: {},
});
nodeById.add(id);
}
function entityNodeId(raw: string): string {
return `ent-${raw
.toLowerCase()
.replace(/[^a-z0-9]+/g, "-")
.replace(/^-+|-+$/g, "")}`;
}
function dedupeEdges(edges: ReadonlyArray<ProceduralGraphEdge>): ProceduralGraphEdge[] {
const out: ProceduralGraphEdge[] = [];
const seen = new Set<string>();
for (const edge of edges) {
const key = `${edge.from}\u0000${edge.to}\u0000${edge.kind}`;
if (seen.has(key)) continue;
seen.add(key);
out.push(edge);
}
return out;
}