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 { existsSync, readdirSync } from "node:fs";
import { basename, join } from "node:path";
import { attentionFlowsDir, brainDirs } from "./paths.ts";
import { listProceduralMemory } from "./procedural-memory.ts";
import { listPendingSkillProposals } from "./skill-proposals.ts";
import { listRecurrenceEntries } from "./recurrence.ts";
import { parsePreference } from "./preference.ts";
import { parseSignal } from "./signal.ts";
import {
resolvePreferenceProvenance,
type SessionRefOrigin,
type SignalSessionRefLookup,
} from "./preference-provenance.ts";
import { BRAIN_PREFERENCE_STATUS, type BrainPreference } from "./types.ts";
import {
assertLaneWrite,
lanePageExists,
listLaneFiles,
parseLanePage,
writeLanePage,
} from "../store/lane-pages.ts";
import { storePreferenceRecords, storeSignalRecords } from "./memory-page-records.ts";
import { isStoreOnly } from "../store/store-only.ts";
export type AttentionFlowAction =
| "open_proposals"
| "high_recurrence"
| "active_procedures"
| "standing_query";
export interface AttentionFlowRecipe {
readonly id: string;
readonly title: string;
readonly actions: ReadonlyArray<AttentionFlowAction>;
/**
* Operator-declared scope tokens for the `standing_query` action. A
* confirmed preference whose `scope` is in this set always surfaces into
* the assembled context. Structural selector - never a natural-language
* phrase - so the attention layer stays language-agnostic.
*/
readonly standingQueryScopes: ReadonlyArray<string>;
readonly sourcePath: string;
}
export interface AttentionFlowSection {
readonly action: AttentionFlowAction;
readonly items: ReadonlyArray<string>;
/**
* Structured standing-instruction facets, present ONLY while the
* evaluation named `standingInstructionFacets` - omitted otherwise,
* so an unset option leaves the section shape byte-identical to the
* legacy one. A preference whose provenance join resolves gains an
* entry; one whose join does not resolve stays absent, an honest
* zero rather than an implied provenance.
*/
readonly facets?: ReadonlyArray<StandingInstructionFacet>;
}
/**
* One confirmed preference surfaced by the `standing_query` action,
* with the origin coordinates its provenance join resolved.
*
* Contract-style cross-reference: this is the preference-corpus sibling
* of `ThreadFacet` in `thread-topics.ts` - a stable key, ordered
* origin coordinates, pure derivation - for a different corpus. A
* thread facet selects the turns of one thread for the coverage pass;
* this facet annotates a standing instruction with the origin its
* evidence cites first. The distinct name is deliberate, so the coverage lane's
* meaning of "facet" stays unambiguous.
*/
export interface StandingInstructionFacet {
/** Stable facet key: `pref:<preference id>`. */
readonly key: string;
readonly preferenceId: string;
readonly scope: string;
/**
* Resolved origins in the preference's `evidenced_by` order - never
* re-sorted, and not a chronological claim; `[0]` is the earliest
* cited origin, not the earliest signal in time.
*/
readonly origins: ReadonlyArray<SessionRefOrigin>;
}
export interface AttentionFlowEvaluationOptions {
/**
* Opt-in standing-instruction provenance (recall lane). Omitted or
* false, every emitted string is the legacy `id (scope)` output and
* sections carry no `facets` field. True, a surfaced preference whose
* provenance join resolves gains an earliest-cited annotation on its
* item string plus a facet entry; the option changes annotations,
* never membership - no preference is admitted that the plain lane
* would not already deliver.
*/
readonly standingInstructionFacets?: boolean;
}
export interface AttentionFlowEvaluation {
readonly flow_id: string;
readonly title: string;
readonly sections: ReadonlyArray<AttentionFlowSection>;
}
export function ensureDefaultAttentionFlows(vault: string): void {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const dir = attentionFlowsDir(vault);
const defaultPath = join(dir, "open-loops.md");
if (lanePageExists(vault, defaultPath)) return;
writeLanePage(
vault,
defaultPath,
{
kind: "brain-attention-flow",
id: "open-loops",
title: "Open loops and learnings",
actions: ["open_proposals", "high_recurrence", "active_procedures"],
status: "active",
},
[
"# Open loops and learnings",
"",
"Declarative flow for context surfaces:",
"- open proposals needing review",
"- strong recurrence candidates",
"- active procedural memory entries",
].join("\n"),
{
overwrite: false,
existsErrorKind: "attention flow",
vaultForRelativePath: vault,
},
);
}
export function listAttentionFlows(vault: string): ReadonlyArray<AttentionFlowRecipe> {
ensureDefaultAttentionFlows(vault);
const dir = attentionFlowsDir(vault);
if (!lanePageExists(vault, dir)) return Object.freeze([]);
const out: AttentionFlowRecipe[] = [];
for (const name of listLaneFiles(vault, dir)) {
const path = join(dir, name);
// Unit F: unreachable `catch { continue }` removed - nothing in this
// body throws (`parseFrontmatter` reads inside its own try, and both
// normalizers are total over `unknown`). A recipe 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, path);
if (fm["kind"] !== "brain-attention-flow") continue;
const actions = normalizeActions(fm["actions"]);
out.push({
id: typeof fm["id"] === "string" ? fm["id"] : name.replace(/\.md$/, ""),
title: typeof fm["title"] === "string" ? fm["title"] : name.replace(/\.md$/, ""),
actions,
standingQueryScopes: normalizeStandingQueryScopes(fm["standing_queries"]),
sourcePath: path,
});
}
return Object.freeze(out);
}
export function evaluateAttentionFlow(
vault: string,
flowId: string,
options: AttentionFlowEvaluationOptions = {},
): AttentionFlowEvaluation {
const flow = listAttentionFlows(vault).find((item) => item.id === flowId);
if (!flow) throw new Error(`attention flow not found: ${flowId}`);
const sections: AttentionFlowSection[] = [];
for (const action of flow.actions) {
if (action === "open_proposals") {
const items = listPendingSkillProposals(vault).map(
(item) => `${item.slug} (${item.patternKind})`,
);
sections.push({ action, items: Object.freeze(items) });
continue;
}
if (action === "high_recurrence") {
const items = listRecurrenceEntries(vault)
.filter((entry) => entry.supportCount >= 3)
.map((entry) => `${entry.contentHash} (${entry.supportCount})`);
sections.push({ action, items: Object.freeze(items) });
continue;
}
if (action === "active_procedures") {
const items = listProceduralMemory(vault)
.filter((entry) => entry.kind === "procedure" || entry.kind === "skill")
.map((entry) => `${entry.title} [${entry.kind}]`);
sections.push({ action, items: Object.freeze(items) });
continue;
}
if (action === "standing_query") {
const facetsWanted = options.standingInstructionFacets === true;
const surfaced = listConfirmedPreferencesByScope(
vault,
flow.standingQueryScopes,
facetsWanted,
);
sections.push({
action,
items: Object.freeze(surfaced.items),
// Key present only under the opt-in: an unset option leaves the
// section byte-identical to the legacy shape.
...(options.standingInstructionFacets === true
? { facets: Object.freeze(surfaced.facets) }
: {}),
});
}
}
return {
flow_id: flow.id,
title: flow.title,
sections: Object.freeze(sections.map((item) => Object.freeze(item))),
};
}
export function renderAttentionFlow(vault: string, flowId: string): string {
const report = evaluateAttentionFlow(vault, flowId);
const lines: string[] = [`# ${report.title}`, ""];
for (const section of report.sections) {
lines.push(`## ${section.action}`);
if (section.items.length === 0) {
lines.push("- (empty)");
} else {
for (const item of section.items) lines.push(`- ${item}`);
}
lines.push("");
}
return `${lines.join("\n").trimEnd()}\n`;
}
function normalizeActions(value: unknown): ReadonlyArray<AttentionFlowAction> {
const allowed = new Set<AttentionFlowAction>([
"open_proposals",
"high_recurrence",
"active_procedures",
"standing_query",
]);
const out: AttentionFlowAction[] = [];
if (Array.isArray(value)) {
for (const item of value) {
if (typeof item !== "string") continue;
const action = item.trim() as AttentionFlowAction;
if (allowed.has(action)) out.push(action);
}
}
if (out.length === 0) return Object.freeze(["open_proposals", "high_recurrence"]);
return Object.freeze([...new Set(out)]);
}
/** Parse the operator-declared `standing_queries` scope tokens. */
function normalizeStandingQueryScopes(value: unknown): ReadonlyArray<string> {
if (!Array.isArray(value)) return Object.freeze([]);
const out: string[] = [];
for (const item of value) {
if (typeof item !== "string") continue;
const scope = item.trim();
if (scope.length > 0) out.push(scope);
}
return Object.freeze([...new Set(out)]);
}
/** Item annotation lead for an origin resolved to a real turn. */
const EARLIEST_CITED_TURN_PREFIX = " [earliest cited turn ";
/** Item annotation lead for an origin resolved to a capture-lifecycle coordinate: the fragment is the hook event's NAME, so the annotation claims the session, never a turn. */
const EARLIEST_CITED_SESSION_PREFIX = " [earliest cited session ";
/** Item annotation suffix. */
const EARLIEST_CITED_SUFFIX = "]";
/**
* Read-only signal-id → `session_ref` lookup over the directories the
* signal readers walk. The on-disk signal id always equals the file's
* basename stem (see `writeSignal`), so a lookup is a direct probe per
* directory; an absent, unreadable, or path-shaped id contributes no
* provenance rather than an error.
*/
function signalSessionRefLookup(vault: string): SignalSessionRefLookup {
if (isStoreOnly({ vault })) {
// A store-only machine: every signal of the fold, by id.
const refs = new Map(
storeSignalRecords(vault, "all").records.map((r) => [r.signal.id, r.signal.session_ref]),
);
return (signalId) => refs.get(signalId);
}
const dirs = brainDirs(vault);
const searchDirs = [dirs.inbox, dirs.processed, dirs.archived];
return (signalId) => {
// Filename-stem ids only: a lookup key is never a path.
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(signalId)) return undefined;
for (const dir of searchDirs) {
const path = join(dir, `${signalId}.md`);
if (!existsSync(path)) continue;
try {
return parseSignal(path).session_ref;
} catch {
// A signal that cannot be parsed proves nothing about where a
// preference came from - no provenance, never a guess.
return undefined;
}
}
return undefined;
};
}
/** The item string plus the facet for one surfaced preference, per the option state. */
interface SurfacedStandingInstruction {
readonly items: string[];
readonly facets: StandingInstructionFacet[];
}
/**
* Confirmed preferences whose `scope` is one the flow declared. Structural
* match on the frontmatter scope token; no natural-language matching. Returns
* `id (scope)` items, sorted for deterministic output. With the facet option
* on, a preference whose provenance join resolves additionally gains an
* earliest-cited annotation on its item string and a facet entry - annotations
* only, never a membership change, so a facet cannot surface a preference the
* plain lane would withhold.
*/
/**
* One read per preference, in file-name order: the page files on an
* unswitched machine, the preference fold's pages on a store-only one
* (`storePreferenceRecords`), so the lane answers in both modes.
*/
function confirmedPreferenceReads(vault: string): Array<() => BrainPreference> {
if (isStoreOnly({ vault })) {
return storePreferenceRecords(vault)
.records.toSorted((a, b) => (basename(a.path) < basename(b.path) ? -1 : 1))
.map((record) => () => record.pref);
}
const dir = brainDirs(vault).preferences;
if (!existsSync(dir)) return [];
return readdirSync(dir)
.toSorted()
.filter((name) => name.endsWith(".md"))
.map((name) => () => parsePreference(join(dir, name)));
}
function listConfirmedPreferencesByScope(
vault: string,
scopes: ReadonlyArray<string>,
facetsWanted: boolean,
): SurfacedStandingInstruction {
const items: string[] = [];
const facets: StandingInstructionFacet[] = [];
if (scopes.length === 0) return { items, facets };
const wanted = new Set(scopes);
const lookup = facetsWanted ? signalSessionRefLookup(vault) : null;
for (const read of confirmedPreferenceReads(vault)) {
try {
const pref = read();
if (
pref.status === BRAIN_PREFERENCE_STATUS.confirmed &&
pref.scope !== undefined &&
wanted.has(pref.scope)
) {
const base = `${pref.id} (${pref.scope})`;
// Off means the legacy bytes: no lookup runs, no annotation is
// composed, the section gains no facet field.
if (lookup === null) {
items.push(base);
continue;
}
const provenance = resolvePreferenceProvenance(
{ id: pref.id, evidenced_by: pref.evidenced_by },
lookup,
);
if (provenance === null) {
// Nothing resolved: the honest plain string, no implied origin.
items.push(base);
continue;
}
const earliest = provenance.origins[0]!;
const prefix =
earliest.kind === "turn" ? EARLIEST_CITED_TURN_PREFIX : EARLIEST_CITED_SESSION_PREFIX;
items.push(
`${base}${prefix}${earliest.sessionKey}#${earliest.fragment}${EARLIEST_CITED_SUFFIX}`,
);
facets.push({
key: provenance.key,
preferenceId: pref.id,
scope: pref.scope,
origins: provenance.origins,
});
}
} catch {
continue;
}
}
return { items, facets };
}
export function buildAttentionContextBlock(
vault: string,
flowIds: ReadonlyArray<string>,
): string | null {
const chunks: string[] = [];
for (const id of flowIds) {
try {
chunks.push(renderAttentionFlow(vault, id));
} catch {
continue;
}
}
if (chunks.length === 0) return null;
return chunks.join("\n");
}