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
/**
* `buildWeeklySynthesis(index, vault, weekEnd, cfg, opts?)` - 7-day
* deterministic summary used by the weekly-synthesis surface.
*
* Shape mirrors `buildDailyBrief` but the window is 7 days back from
* `weekEnd` (ISO date). On top of the daily envelope the weekly
* synthesis adds:
*
* - `retired`: list of retire transitions inside the window.
* - `contradictions`: combined list of `signal-suppressed` events
* plus `apply-evidence` events where the payload `result` is
* `"violated"`. Both surfaces signal a clash between the agent's
* stated rule and the underlying activity.
*
* Design anchor: `docs/brainstorm/temporal-synthesis/design.md`,
* Task 7 in `plan.md`.
*/
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join } from "node:path";
import { extractWikilinkRichBodies, parseWikilinkRich } from "../link-graph/parse-wikilink.ts";
import { isoSecond, MS_PER_DAY, msToWholeDays } from "./../time.ts";
import type { BrainLogEventKind, ResolvedBrainTemporalConfig } from "./../types.ts";
import { BRAIN_LOG_EVENT_KIND } from "./../types.ts";
import { selectEvents } from "./select-events.ts";
import {
collectSourcePointers,
collectTransitions,
computeVaultDelta,
countByKind,
type PeriodStatusTransition,
type PeriodVaultDelta,
} from "./period-common.ts";
import type { TemporalEvent, TimelineIndex } from "./types.ts";
/** Window length of the weekly synthesis, in days. */
const WEEK_DAYS = 7;
export interface WeeklyContradiction {
readonly at: string;
readonly kind: "signal-suppressed" | "evidence-violated";
readonly prefId?: string;
readonly topic?: string;
readonly reason?: string;
readonly artifact?: string;
}
export interface WeeklyRetirement {
readonly at: string;
readonly prefId: string;
readonly link: string;
}
export interface WeeklyTopSource {
/** Vault-relative path of the nominated note. */
readonly path: string;
readonly score: number;
/** One-line deterministic rationale. */
readonly why: string;
/** Per-signal breakdown behind the score. */
readonly signals: {
readonly recencyDays: number;
readonly inboundLinks: number;
readonly outboundLinks: number;
};
}
export interface WeeklySynthesisEnvelope {
readonly windowStart: string;
readonly windowEnd: string;
readonly eventsByKind: Readonly<Partial<Record<BrainLogEventKind, number>>>;
readonly statusTransitions: ReadonlyArray<PeriodStatusTransition>;
readonly retired: ReadonlyArray<WeeklyRetirement>;
readonly contradictions: ReadonlyArray<WeeklyContradiction>;
readonly vaultDelta: PeriodVaultDelta;
readonly sourcePointers: ReadonlyArray<string>;
readonly generatedAt: string;
/**
* Weekly top-source (t_a8d49eae): the single most-developable note
* of the window - recency + inbound links + link centrality.
* Absent when no candidate note was modified inside the window, so
* historic envelopes stay byte-identical.
*/
readonly topSource?: WeeklyTopSource;
}
export interface BuildWeeklySynthesisOptions {
/** Wall clock for `generatedAt`; defaults to `new Date()`. */
readonly now?: Date;
}
export function buildWeeklySynthesis(
index: TimelineIndex,
vault: string,
weekEnd: string,
_cfg: ResolvedBrainTemporalConfig,
opts: BuildWeeklySynthesisOptions = {},
): WeeklySynthesisEnvelope {
// `_cfg` is part of the helper signature for parity
// with sibling projections and forward compatibility (weekday-
// alignment overrides will read `_cfg.weekly_start_dow` in a
// future release); the brief itself is a pure projection over the
// index and does not re-touch disk.
const windowEndMs = Date.parse(`${weekEnd}T00:00:00Z`);
if (!Number.isFinite(windowEndMs)) {
throw new Error(`buildWeeklySynthesis: invalid weekEnd ${JSON.stringify(weekEnd)}`);
}
const windowStartMs = windowEndMs - WEEK_DAYS * MS_PER_DAY;
const windowStart = isoSecond(new Date(windowStartMs));
const windowEndIso = isoSecond(new Date(windowEndMs));
const generatedAt = (opts.now ?? new Date()).toISOString();
const events = selectEvents(index, {
since: windowStart,
until: windowEndIso,
});
const transitions = collectTransitions(events);
const vaultDelta = computeVaultDelta(events, transitions);
const retired = transitions
.filter((t) => t.kind === "retirement")
.map((t) => Object.freeze({ at: t.at, prefId: t.prefId, link: t.link }));
const contradictions = collectContradictions(events);
const topSource = nominateTopSource(vault, windowStartMs, windowEndMs);
return Object.freeze({
...(topSource !== null ? { topSource } : {}),
windowStart,
windowEnd: windowEndIso,
eventsByKind: Object.freeze(countByKind(events)),
statusTransitions: Object.freeze(transitions),
retired: Object.freeze(retired),
contradictions: Object.freeze(contradictions),
vaultDelta: Object.freeze(vaultDelta),
sourcePointers: Object.freeze(collectSourcePointers(events)),
generatedAt,
});
}
function collectContradictions(events: ReadonlyArray<TemporalEvent>): WeeklyContradiction[] {
const out: WeeklyContradiction[] = [];
for (const ev of events) {
if (ev.kind === BRAIN_LOG_EVENT_KIND.signalSuppressed) {
out.push(makeContradiction("signal-suppressed", ev));
} else if (ev.kind === BRAIN_LOG_EVENT_KIND.applyEvidence && ev.result === "violated") {
out.push(makeContradiction("evidence-violated", ev));
}
}
out.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
return out;
}
function makeContradiction(
kind: WeeklyContradiction["kind"],
ev: TemporalEvent,
): WeeklyContradiction {
return Object.freeze({
at: ev.at,
kind,
...(ev.prefId !== undefined ? { prefId: ev.prefId } : {}),
...(ev.topic !== undefined ? { topic: ev.topic } : {}),
...(ev.reason !== undefined ? { reason: ev.reason } : {}),
...(ev.artifact !== undefined ? { artifact: ev.artifact } : {}),
});
}
// ----- Weekly top-source (t_a8d49eae) ---------------------------------------
// Machine-owned content never nominates: logs, signals, machine
// stores, generated digests, and rule files are not "notes worth
// developing further".
const TOP_SOURCE_EXCLUDED_PREFIXES: ReadonlyArray<string> = Object.freeze([
"Brain/log/",
"Brain/inbox/",
"Brain/retired/",
"Brain/preferences/",
"Brain/.snapshots/",
"Brain/snapshots/",
"Brain/search/",
"Brain/procedural/",
"Brain/recurrence/",
"Brain/truth/",
"Brain/triggers/",
"Brain/continuity/",
"Brain/dead-ends/",
"Brain/foresight/",
"Brain/_",
"Brain/active",
"Brain/pinned",
]);
const SKIPPED_DIR_NAMES: ReadonlySet<string> = new Set([
".git",
"node_modules",
".open-second-brain",
".obsidian",
".trash",
".stversions",
]);
interface TopSourceCandidate {
readonly relPath: string;
readonly mtimeMs: number;
}
function walkMarkdown(vault: string): string[] {
const out: string[] = [];
const stack: string[] = [""];
while (stack.length > 0) {
const rel = stack.pop()!;
const abs = rel === "" ? vault : join(vault, rel);
let names: string[];
try {
names = readdirSync(abs);
} catch {
continue;
}
for (const name of names.toSorted()) {
const childRel = rel === "" ? name : `${rel}/${name}`;
let isDir: boolean;
try {
isDir = statSync(join(vault, childRel)).isDirectory();
} catch {
continue;
}
if (isDir) {
if (SKIPPED_DIR_NAMES.has(name) || name.startsWith(".")) continue;
stack.push(childRel);
} else if (name.endsWith(".md")) {
out.push(childRel);
}
}
}
return out.toSorted();
}
function excluded(relPath: string): boolean {
return TOP_SOURCE_EXCLUDED_PREFIXES.some((prefix) => relPath.startsWith(prefix));
}
function pageNames(relPath: string): string[] {
const stripped = relPath.endsWith(".md") ? relPath.slice(0, -3) : relPath;
const slash = stripped.lastIndexOf("/");
return slash >= 0 ? [stripped, stripped.slice(slash + 1)] : [stripped];
}
/**
* Nominate the most-developable note of the window: every candidate
* modified inside [windowStart, windowEnd) scores
* `0.5*recency + 0.3*inbound/(inbound+3) + 0.2*outbound/(outbound+5)`
* over the whole-vault link graph. Null when nothing qualified.
*/
function nominateTopSource(
vault: string,
windowStartMs: number,
windowEndMs: number,
): WeeklyTopSource | null {
const all = walkMarkdown(vault);
const candidates: TopSourceCandidate[] = [];
for (const relPath of all) {
if (excluded(relPath)) continue;
let mtimeMs: number;
try {
mtimeMs = statSync(join(vault, relPath)).mtimeMs;
} catch {
continue;
}
if (mtimeMs >= windowStartMs && mtimeMs < windowEndMs) {
candidates.push({ relPath, mtimeMs });
}
}
if (candidates.length === 0) return null;
// Inbound counts over the WHOLE vault: links from machine files
// still count as evidence of centrality, only nomination is scoped.
const nameToCandidate = new Map<string, string>();
for (const c of candidates) {
for (const name of pageNames(c.relPath)) {
if (!nameToCandidate.has(name)) nameToCandidate.set(name, c.relPath);
}
}
const inbound = new Map<string, number>();
const outbound = new Map<string, number>();
for (const relPath of all) {
let content: string;
try {
content = readFileSync(join(vault, relPath), "utf8");
} catch {
continue;
}
let links = 0;
for (const body of extractWikilinkRichBodies(content)) {
const target = parseWikilinkRich(body).target;
if (target === "") continue;
links++;
const hit = nameToCandidate.get(target);
if (hit !== undefined && hit !== relPath) {
inbound.set(hit, (inbound.get(hit) ?? 0) + 1);
}
}
outbound.set(relPath, links);
}
let best: WeeklyTopSource | null = null;
for (const c of candidates) {
// Floored at 0 here rather than in the shared conversion: a note
// stamped after the window end is a real condition, but "modified -2d
// before window end" is not a sentence this label can carry.
const recencyDays = Math.max(0, msToWholeDays(windowEndMs - c.mtimeMs));
const recency = Math.max(0, 1 - (windowEndMs - c.mtimeMs) / (windowEndMs - windowStartMs));
const inboundLinks = inbound.get(c.relPath) ?? 0;
const outboundLinks = outbound.get(c.relPath) ?? 0;
const score =
Math.round(
(0.5 * recency +
0.3 * (inboundLinks / (inboundLinks + 3)) +
0.2 * (outboundLinks / (outboundLinks + 5))) *
10000,
) / 10000;
const candidate: WeeklyTopSource = Object.freeze({
path: c.relPath,
score,
why:
`Modified ${recencyDays}d before window end with ${inboundLinks} inbound and ` +
`${outboundLinks} outbound link(s) - the strongest develop-next lead of the window.`,
signals: Object.freeze({ recencyDays, inboundLinks, outboundLinks }),
});
if (best === null || score > best.score || (score === best.score && c.relPath < best.path)) {
best = candidate;
}
}
return best;
}