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
/**
* Brain digest (design doc Β§8).
*
* Read-only renderer over Brain/log/ + Brain/preferences/ +
* Brain/retired/. Default window: the last 24 hours, ending at
* `opts.until ?? now`. Both Markdown and JSON outputs are supported;
* the JSON form follows Β§8.2 verbatim so downstream consumers (Hermes
* cron, CI scripts) can parse it without surprises.
*
* Sections, each rendered only when non-empty:
*
* 1. **New (unconfirmed, in trial)** β preferences with `status:
* unconfirmed` and `created_at` inside the window.
* 2. **Confirmed** β preferences with `confirmed_at` inside the
* window.
* 3. **Retired** β retired entries with `retired_at` inside the
* window.
* 4. **Confidence shifts** β preferences whose confidence changed
* inside the window. The current Brain state does not carry an
* explicit `confidence_history`; the design accepts a graceful
* degradation here. We read `dream` log events: when their
* payload exposes a `confidence_shifts` (singular bullet) or
* `confidence_changes` sub-list, we parse those. If the payload
* is absent, the section is empty.
* 5. **Contradictions** β events of kind `contradicted` or `dream`
* events emitting a `contradictions` sub-list. Same graceful
* degradation: empty when the payload is not produced.
*
* Empty window β one-line Markdown `Brain digest β <date>: no changes`
* (or JSON with `summary.empty: true`). The function returns both the
* rendered string and an `empty` flag so the CLI can implement
* `--silent-if-empty` (exit 2) without re-parsing.
*
* The function is pure read. It does not mutate signals, preferences,
* retired entries, the log, or the snapshots.
*/
import { withPrivateWithheld } from "../store/caller-reach.ts";
import { readTopicReview, renderTopicReview } from "../topics/review.ts";
import { readerRefView } from "./artifact-ref-view.ts";
import { closedCollectError } from "./maintenance/collect.ts";
import { renderPrefLink, type LinkOutputFormat } from "./wikilink.ts";
import { BRAIN_RETIRED_REASON } from "./types.ts";
import type {
DigestData,
DigestJson,
RenderDigestOptions,
RenderDigestResult,
} from "./digest-types.ts";
import { ONE_DAY_MS, collectDigestData } from "./digest-collect.ts";
import { isEmpty } from "./digest-analysis.ts";
export type {
DigestFormat,
RenderDigestOptions,
RenderDigestResult,
DigestJsonNewUnconfirmed,
DigestJsonConfirmed,
DigestJsonRetired,
DigestJsonConfidenceShift,
DigestJsonContradiction,
DigestJsonTopApplied,
DigestJsonTopReferenced,
DigestJsonMostAppliedEntry,
DigestJsonMostApplied,
DigestJsonAgentSummary,
DigestJsonMergeSuggestion,
DigestJsonConnectionHealth,
DigestJson,
} from "./digest-types.ts";
// ----- Entry point ----------------------------------------------------------
export function renderDigest(vault: string, opts: RenderDigestOptions = {}): RenderDigestResult {
const format = opts.format ?? "markdown";
const now = opts.now ?? new Date();
const until = opts.until ?? now;
const since = opts.since ?? new Date(until.getTime() - ONE_DAY_MS);
if (Number.isNaN(since.getTime()) || Number.isNaN(until.getTime())) {
throw new TypeError("renderDigest: `since` and `until` must be valid Dates");
}
if (since.getTime() > until.getTime()) {
throw new RangeError(
`renderDigest: since (${since.toISOString()}) is after until (${until.toISOString()})`,
);
}
const collected = collectDigestData(
vault,
since,
until,
opts.agentScope,
readerRefView(vault, opts.readable, opts.withholdsPrivate === true),
);
// A digest rendered for a reader below local reach (a `readable`
// filter) names a failed scan without its raised message, which can
// carry a host path.
const data =
opts.readable === undefined
? collected
: { ...collected, collect_errors: collected.collect_errors.map(closedCollectError) };
const empty = isEmpty(data);
if (format === "json") {
const payload: DigestJson = {
schema_version: 1,
generated_at: now.toISOString(),
window: { since: since.toISOString(), until: until.toISOString() },
summary: {
new_unconfirmed_count: data.new_unconfirmed.length,
confirmed_count: data.confirmed.length,
retired_count: data.retired.length,
confidence_shift_count: data.confidence_shifts.length,
contradiction_count: data.contradictions.length,
empty,
},
new_unconfirmed: data.new_unconfirmed,
confirmed: data.confirmed,
retired: data.retired,
confidence_shifts: data.confidence_shifts,
contradictions: data.contradictions,
top_applied: data.top_applied,
top_referenced: data.top_referenced,
merge_suggestions: data.merge_suggestions,
agent_summary: data.agent_summary,
most_applied: data.most_applied,
connection_health: data.connection_health,
actions: data.actions,
...(data.collect_errors.length > 0
? {
collect_errors: data.collect_errors.map((e) => ({
scan: e.signal,
message: e.message,
})),
}
: {}),
// Guarded: dreamSummary may arrive from an untyped JSON-RPC
// boundary (or from a future caller that has not populated
// every array). Optional-chain the inner length read.
uncertain_count: opts.dreamSummary?.uncertain?.length ?? 0,
quarantined_count: opts.dreamSummary?.quarantined?.length ?? 0,
...(opts.doctorResult?.trust_verdict !== undefined
? { trust_verdict: opts.doctorResult.trust_verdict }
: {}),
};
return Object.freeze({
content: JSON.stringify(payload, null, 2) + "\n",
empty,
});
}
// Markdown.
const linkOutputFormat = opts.linkOutputFormat ?? "wikilink";
const baseMd = empty
? renderEmptyMarkdown(until)
: renderMarkdown(data, since, until, linkOutputFormat);
const trustSection = renderTrustSection(opts.doctorResult, opts.dreamSummary);
// What the user is asked about topics (merges, quiet topics), read at
// the caller's reach; absent when there is nothing to ask.
const topicSection = withPrivateWithheld(opts.withholdsPrivate === true, () =>
renderTopicReview(readTopicReview(now.getTime(), opts.configPath)),
);
const sections = [baseMd, trustSection, topicSection].filter((part) => part !== "");
const content = sections.join("\n");
return Object.freeze({ content, empty: empty && topicSection === "" });
}
/**
* Markdown `## Trust` section (v0.10.16). Rendered only when either
* a doctor result or a dream summary is threaded through the digest
* options - otherwise legacy output stays bit-identical.
*/
function renderTrustSection(
doctor?: import("./doctor.ts").RunDoctorResult,
dream?: import("./dream.ts").DreamRunSummary,
): string {
if (doctor === undefined && dream === undefined) return "";
const lines: string[] = ["## Trust", ""];
if (doctor?.trust_verdict !== undefined) {
lines.push(`- Verdict: **${doctor.trust_verdict}**`);
}
if (dream !== undefined) {
lines.push(`- Uncertain: ${dream.uncertain.length}`);
lines.push(`- Quarantined: ${dream.quarantined.length}`);
}
lines.push("");
return lines.join("\n");
}
// ----- Data collection ------------------------------------------------------
function renderEmptyMarkdown(until: Date): string {
// Single-line collapse per Β§8 paragraph above the listing.
const ymd = until.toISOString().slice(0, 10);
return `Brain digest β ${ymd}: no changes\n`;
}
function renderMarkdown(
data: DigestData,
since: Date,
until: Date,
linkOutputFormat: LinkOutputFormat,
): string {
const sinceIso = since.toISOString();
const untilIso = until.toISOString();
const windowHours = Math.round((until.getTime() - since.getTime()) / (60 * 60 * 1000));
const lines: string[] = [];
lines.push(
`# Brain digest β ${untilIso.slice(0, 16)}Z (${windowHours}h)`,
"",
`Window: ${sinceIso} β ${untilIso}`,
"",
);
if (data.new_unconfirmed.length > 0) {
lines.push("## New (unconfirmed, in trial)", "");
for (const item of data.new_unconfirmed) {
const scope = item.scope ?? "β";
const trialDay = item.unconfirmed_until.slice(0, 10);
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} β ${scope}, ${item.signal_count} signals, trial ends ${trialDay}`,
);
}
lines.push("");
}
if (data.confirmed.length > 0) {
lines.push("## Confirmed", "");
for (const item of data.confirmed) {
const scope = item.scope ?? "β";
const artifact = item.first_applied_artifact ?? "_(none)_";
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} β ${scope}, first applied in ${artifact}`,
);
}
lines.push("");
}
if (data.retired.length > 0) {
lines.push("## Retired", "");
for (const item of data.retired) {
const scope = item.scope ?? "β";
const detail =
item.reason === BRAIN_RETIRED_REASON.staleNoEvidence && item.days_stale !== null
? `${item.reason} (${item.days_stale} days)`
: item.reason;
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} β ${scope}, ${detail}`,
);
}
lines.push("");
}
if (data.most_applied.entries.length > 0) {
lines.push(
`## Most-applied (${data.most_applied.window_days}d) (${data.most_applied.entries.length})`,
"",
);
for (const item of data.most_applied.entries) {
const scope = item.scope ?? "β";
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} β ${scope}, ${item.applied_in_window} applied`,
);
}
lines.push("");
}
if (data.agent_summary.length > 0) {
lines.push(`## Agent summary (${data.agent_summary.length})`, "");
for (const item of data.agent_summary) {
const parts = [
`**${item.agent}**`,
`${item.total_events} events`,
`(feedback: ${item.feedback_count}, apply: ${item.apply_evidence_count}, note: ${item.note_count})`,
];
if (item.confirmed_attributed > 0) parts.push(`β ${item.confirmed_attributed} confirmed`);
if (item.retired_attributed > 0) parts.push(`β ${item.retired_attributed} retired`);
lines.push(`- ${parts.join(" ")}`);
}
lines.push("");
}
if (data.top_applied.length > 0) {
lines.push(`## Top applied (${data.top_applied.length})`, "");
for (const item of data.top_applied) {
const scope = item.scope ?? "β";
const stats = `applied: ${item.applied_count}, violated: ${item.violated_count}`;
const tags = item.status === "quarantine" ? " [quarantine]" : "";
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} β ${scope}, ${stats}${tags}`,
);
}
lines.push("");
}
if (data.top_referenced.length > 0) {
lines.push(`## Top referenced (${data.top_referenced.length})`, "");
for (const item of data.top_referenced) {
const scope = item.scope ?? "β";
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} β ${scope}, ${item.backlink_count} inbound`,
);
}
lines.push("");
}
// Connection health is always rendered when vault has nodes β it
// reflects vault-wide structural state, not windowed change.
if (data.connection_health.total_nodes > 0) {
const ch = data.connection_health;
const pct = Math.round(ch.link_density * 100);
lines.push(
"## Connection health",
"",
`- Total nodes: ${ch.total_nodes}`,
`- Linked (β₯1 inbound): ${ch.linked_nodes}`,
`- Orphans (0 inbound): ${ch.orphan_nodes}`,
`- Mean backlinks: ${ch.mean_backlinks}`,
`- Median backlinks: ${ch.median_backlinks}`,
`- Link density: ${pct}%`,
"",
);
}
// Ranked maintenance actions (v0.10.15). Same window-independent
// shape as connection-health: surface only when the scorer
// returned anything, so empty vaults stay quiet.
if (data.actions.length > 0) {
lines.push(`## Actions (${data.actions.length})`, "");
for (const a of data.actions) {
lines.push(`- [${a.category}] impact ${a.impact} β ${a.title}`);
}
lines.push("");
}
if (data.merge_suggestions.length > 0) {
lines.push(`## Merge suggestions (${data.merge_suggestions.length})`, "");
for (const item of data.merge_suggestions) {
const scope = item.scope ?? "β";
lines.push(
`- ${renderPrefLink({ id: item.a, principle: item.principle_a, format: linkOutputFormat })}` +
` β ${renderPrefLink({ id: item.b, principle: item.principle_b, format: linkOutputFormat })}` +
` β topic '${item.topic}', scope ${scope}, jaccard ${item.jaccard.toFixed(2)}`,
);
}
lines.push("");
}
if (data.confidence_shifts.length > 0) {
lines.push("## Confidence shifts", "");
for (const item of data.confidence_shifts) {
const stats =
item.applied_count !== null && item.violated_count !== null
? ` (applied: ${item.applied_count}, violated: ${item.violated_count})`
: "";
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} ${item.from} β ${item.to}${stats}`,
);
}
lines.push("");
}
if (data.contradictions.length > 0) {
lines.push("## Contradictions", "");
for (const item of data.contradictions) {
const topic = item.topic ? ` (topic: ${item.topic})` : "";
lines.push(
`- ${renderPrefLink({ id: item.id, principle: item.principle, format: linkOutputFormat })} β ${item.description}${topic}`,
);
}
lines.push("");
}
return lines.join("\n").replace(/\n+$/, "\n");
}