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
/**
* Decision panel as a write-session kind
* (Agent Write Contract Suite, t_0cc6fdff on the t_bc36a8a2 kernel).
*
* The panel rides the session kernel instead of owning a second state
* machine: persona steps and the synthesis step reuse the kernel's
* correction loop, retry cap, TTL, review gate, commit, and audit. OSB
* sequences the lenses and validates the texts; the calling agent
* supplies every generated word - the no-LLM-in-core rule holds.
*
* Step walk: `persona:<slug>` for each persona in declared order, then
* `synthesis`, then the rendered decision note commits to the session
* target (default `Brain/decisions/panels/panel-<date>-<topic>.md`).
*/
import {
WriteSessionRequestError,
commitArtifact,
loadLiveSession,
recordFailedAttempt,
resolveNow,
sessionEnvelope,
submitToSession,
DEFAULT_RETRY_CAP,
DEFAULT_TTL_MS,
} from "./engine.ts";
import { createWriteSession, saveWriteSession } from "./store.ts";
import { loadPersonas } from "./personas.ts";
import { inspectExistingTarget, validateTargetPath } from "./validate.ts";
import { formatFrontmatter, slugify } from "../../vault.ts";
import {
deterministicPrefix,
emitPromptPrefixMetric,
summarizePrefixPass,
type PromptPrefix,
} from "../prompt-prefix.ts";
import { isoSecond } from "../time.ts";
import type {
WriteSessionEnvelope,
WriteSessionError,
WriteSessionPersona,
WriteSessionRecord,
} from "./types.ts";
/** Per-step text cap - a lens answer, not an essay collection. */
export const PANEL_STEP_MAX_CHARS = 8000;
const SYNTHESIS_STEP = "synthesis";
export interface OpenPanelSessionInput {
readonly agent: string;
readonly topic: string;
/** Persona slugs to convene, in order; defaults to every loaded persona. */
readonly personas?: ReadonlyArray<string>;
/** Override the default panels namespace target. */
readonly targetPath?: string;
readonly requireReview?: boolean;
readonly retryCap?: number;
readonly ttlMs?: number;
readonly now?: string;
}
/** Open a panel session; the first envelope carries persona step one. */
export function openPanelSession(
vault: string,
input: OpenPanelSessionInput,
): WriteSessionEnvelope {
const topic = input.topic.trim();
if (topic === "") {
throw new WriteSessionRequestError("panel topic must not be empty");
}
const personas = selectPersonas(loadPersonas(vault), input.personas);
const now = resolveNow(input.now);
const targetPath =
input.targetPath ?? `Brain/decisions/panels/panel-${now.slice(0, 10)}-${slugify(topic)}.md`;
const targetErrors = validateTargetPath(targetPath);
if (targetErrors.length > 0) {
throw new WriteSessionRequestError(
`target rejected: ${targetErrors[0]!.message}`,
targetErrors,
);
}
const first = personas[0]!;
const expiresAt = new Date(Date.parse(now) + (input.ttlMs ?? DEFAULT_TTL_MS)).toISOString();
const record = createWriteSession(vault, now, (id) =>
Object.freeze({
id,
kind: "panel" as const,
status: "needs-llm-step" as const,
step: `persona:${first.slug}`,
agent: input.agent.trim() || "unknown",
createdAt: now,
updatedAt: now,
expiresAt,
attempts: 0,
retryCap: input.retryCap ?? DEFAULT_RETRY_CAP,
targetPath,
intent: "create" as const,
requireReview: input.requireReview === true,
prompt: personaPrompt(first, topic),
schemaType: null,
topic,
personas,
responses: {},
pendingArtifact: null,
lastErrors: [],
failReason: null,
}),
);
return sessionEnvelope(record);
}
export interface SubmitPanelStepInput {
readonly sessionId: string;
readonly text: string;
readonly now?: string;
/**
* Opt-in: when the synthesis step commits, emit one run-level
* `prompt_prefix` metric for the whole panel pass. Omitted/false keeps
* the commit byte-identical and writes no metric.
*/
readonly promptPrefixMetric?: boolean;
}
/** Submit the current panel step (persona answer or synthesis). */
export function submitToPanelSession(
vault: string,
input: SubmitPanelStepInput,
): WriteSessionEnvelope {
const now = resolveNow(input.now);
const session = loadLiveSession(vault, input.sessionId, now);
if (session.kind !== "panel") {
throw new WriteSessionRequestError(
`session ${session.id} is an '${session.kind}' session - use the artifact submit surface`,
);
}
const errors = validateStepText(input.text);
if (errors.length > 0) {
return recordFailedAttempt(vault, session, errors, now);
}
const text = input.text.trim();
if (session.step === SYNTHESIS_STEP) {
// Commit-time collision guard: panel sessions always carry `create`
// intent, and create NEVER overwrites - same contract as the
// artifact flow. An occupied target (operator-specified, or a
// same-day rerun of the same topic) is a structured error, not a
// silent overwrite.
if (inspectExistingTarget(vault, session.targetPath) !== null) {
return recordFailedAttempt(
vault,
session,
[
Object.freeze({
code: "target-exists",
path: "target",
message: `${session.targetPath} already exists; abandon and reopen with --target`,
}),
],
now,
);
}
const note = renderPanelNote(session, text, now);
// The synthesis is the last generation handoff of the pass; every
// persona step and the synthesis shared `panelPrefix(topic)`, so the
// pass is byte-stable by construction. Record it (opt-in, fail-soft).
emitPanelPrefixMetric(vault, session, now, input.promptPrefixMetric);
if (session.requireReview) {
const parked: WriteSessionRecord = Object.freeze({
...session,
status: "needs-review" as const,
updatedAt: now,
responses: Object.freeze({ ...session.responses, [SYNTHESIS_STEP]: text }),
pendingArtifact: note,
lastErrors: [],
prompt: "Awaiting operator review - no further generation needed.",
});
saveWriteSession(vault, parked);
return sessionEnvelope(parked);
}
return commitArtifact(
vault,
Object.freeze({
...session,
responses: Object.freeze({ ...session.responses, [SYNTHESIS_STEP]: text }),
}),
note,
now,
);
}
// Persona step accepted: record the answer, advance, reset attempts.
const responses = Object.freeze({ ...session.responses, [session.step]: text });
const next = nextStep(session, session.step);
const advanced: WriteSessionRecord = Object.freeze({
...session,
status: "needs-llm-step" as const,
step: next,
attempts: 0,
updatedAt: now,
responses,
lastErrors: [],
prompt:
next === SYNTHESIS_STEP
? synthesisPrompt({ ...session, responses })
: personaPrompt(
session.personas.find((p) => `persona:${p.slug}` === next)!,
session.topic ?? "",
),
});
saveWriteSession(vault, advanced);
return sessionEnvelope(advanced);
}
export interface DispatchSubmitInput {
readonly sessionId: string;
readonly text: string;
readonly now?: string;
/** Forwarded to the panel flow; ignored for artifact sessions. */
readonly promptPrefixMetric?: boolean;
}
/**
* Kind-agnostic submit for surfaces that take a bare session id (CLI
* `brain session submit`, the MCP tool): routes to the artifact or
* panel flow based on the stored session kind.
*/
export function dispatchSubmit(vault: string, input: DispatchSubmitInput): WriteSessionEnvelope {
const now = resolveNow(input.now);
const session = loadLiveSession(vault, input.sessionId, now);
if (session.kind === "panel") {
return submitToPanelSession(vault, {
sessionId: input.sessionId,
text: input.text,
now,
promptPrefixMetric: input.promptPrefixMetric,
});
}
return submitToSession(vault, { sessionId: input.sessionId, artifact: input.text, now });
}
// ----- internals -------------------------------------------------------------
/**
* Emit one run-level `prompt_prefix` metric for a completed panel pass.
* Every step (persona answers + synthesis) shared `panelPrefix(topic)`,
* so the pass is fully stable by construction: `call_count` and
* `stable_count` both equal personas + 1. Opt-in and fail-soft.
*/
function emitPanelPrefixMetric(
vault: string,
session: WriteSessionRecord,
now: string,
gate: boolean | undefined,
): void {
if (!gate) return;
const prefix = panelPrefix(session.topic);
const prefixes = Array.from({ length: session.personas.length + 1 }, () => prefix);
emitPromptPrefixMetric(
vault,
{
runAt: isoSecond(new Date(now)),
summary: summarizePrefixPass({ kind: "write_session", prefixes }),
},
gate,
);
}
function selectPersonas(
loaded: ReadonlyArray<WriteSessionPersona>,
requested: ReadonlyArray<string> | undefined,
): ReadonlyArray<WriteSessionPersona> {
if (requested === undefined || requested.length === 0) return loaded;
const bySlug = new Map(loaded.map((p) => [p.slug, p]));
const selected: WriteSessionPersona[] = [];
// Duplicates would break step progression: `nextStep` walks the
// persona list by indexOf, so a repeated slug loops on itself and
// the session never reaches synthesis.
const seen = new Set<string>();
for (const rawSlug of requested) {
const slug = rawSlug.trim();
if (slug === "") {
throw new WriteSessionRequestError("persona slug must not be empty");
}
if (seen.has(slug)) {
throw new WriteSessionRequestError(`duplicate persona '${slug}' requested`);
}
seen.add(slug);
const persona = bySlug.get(slug);
if (persona === undefined) {
throw new WriteSessionRequestError(
`unknown persona '${slug}' - available: ${loaded.map((p) => p.slug).join(", ")}`,
);
}
selected.push(persona);
}
return Object.freeze(selected);
}
function validateStepText(text: string): ReadonlyArray<WriteSessionError> {
if (typeof text !== "string" || text.trim() === "") {
return Object.freeze([
Object.freeze({ code: "step-empty", path: "body", message: "step text must not be empty" }),
]);
}
if (text.length > PANEL_STEP_MAX_CHARS) {
return Object.freeze([
Object.freeze({
code: "step-too-long",
path: "body",
message: `step text exceeds ${PANEL_STEP_MAX_CHARS} characters`,
}),
]);
}
return Object.freeze([]);
}
function nextStep(session: WriteSessionRecord, current: string): string {
const steps = session.personas.map((p) => `persona:${p.slug}`);
const index = steps.indexOf(current);
return index >= 0 && index < steps.length - 1 ? steps[index + 1]! : SYNTHESIS_STEP;
}
/**
* The cacheable preamble shared by every generation step of one panel
* pass: persona answers and the synthesis all lead with the same
* topic frame, so a provider prefix cache could reuse these bytes
* across the whole deliberation. Routed through `deterministicPrefix`
* to make that stability explicit; the bytes are unchanged.
*/
function panelPrefix(topic: string | null): PromptPrefix {
return deterministicPrefix({
kind: "write_session",
segments: [`Decision topic: ${topic}`, "\n\n"],
});
}
function personaPrompt(persona: WriteSessionPersona, topic: string): string {
return (
panelPrefix(topic).prefix +
`Answer as the '${persona.slug}' panelist (${persona.lens}).\n${persona.prompt}`
);
}
function synthesisPrompt(session: WriteSessionRecord): string {
const answers = session.personas
.map((p) => `### ${p.lens} (${p.slug})\n${session.responses[`persona:${p.slug}`] ?? ""}`)
.join("\n\n");
return (
panelPrefix(session.topic).prefix +
`Every panelist has answered:\n\n${answers}\n\n` +
"Synthesize the deliberation into a recommendation: state the decision, the strongest supporting argument per lens, the unresolved tensions, and the conditions that would reverse it."
);
}
/** Deterministic decision note - same session state, same bytes. */
function renderPanelNote(session: WriteSessionRecord, synthesis: string, now: string): string {
const metadata = {
kind: "decision-panel",
topic: session.topic ?? "",
created_at: now.replace(/\.\d{3}Z$/u, "Z"),
session: session.id,
agent: session.agent,
personas: session.personas.map((p) => p.slug),
tags: ["brain", "brain/decision-panel"],
};
const lines: string[] = [`# Panel: ${session.topic ?? ""}`, ""];
for (const persona of session.personas) {
lines.push(`## ${persona.lens} (${persona.slug})`, "");
lines.push(session.responses[`persona:${persona.slug}`] ?? "", "");
}
lines.push("## Synthesis", "", synthesis);
return formatFrontmatter(metadata, lines.join("\n"));
}