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
/**
* Calendar-aware Brain tools (t_f7b82ba4): recurring obligations
* (`brain_obligation`) and deterministic agenda synthesis
* (`brain_agenda`). The kernel never reaches a calendar API - the host
* runtime fetches events and passes them in; these tools are pure
* vault-native bookkeeping and pure analysis respectively.
*/
import { resolveAgentName } from "../../core/config.ts";
import {
addObligation,
completeObligation,
listObligations,
removeObligation,
noObligationError,
showObligation,
type ObligationListItem,
type ObligationPage,
} from "../../core/brain/obligations.ts";
import { BRAIN_OBLIGATIONS_REL } from "../../core/brain/path-constants.ts";
import { slugify } from "../../core/vault.ts";
import {
synthesizeAgenda,
type AgendaEventInput,
type AgendaSnapshot,
} from "../../core/brain/agenda.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { coerceStr, coerceStrList, unknownOperationError } from "../coerce.ts";
import { readableAtContextReachOrUndefined } from "./reach-readable.ts";
import { laneVault } from "./lane-vault.ts";
function pageJson(page: ObligationPage): Record<string, unknown> {
return {
slug: page.slug,
title: page.title,
cadence: page.cadence,
created_at: page.createdAt,
anchor: page.anchor,
last_done: page.lastDone,
next_due: page.nextDue,
completions: page.completions,
path: page.path,
};
}
function listItemJson(item: ObligationListItem): Record<string, unknown> {
return {
slug: item.slug,
title: item.title,
cadence: item.cadence,
next_due: item.nextDue,
last_done: item.lastDone,
overdue: item.overdue,
days_until_due: item.daysUntilDue,
};
}
/** The vault-relative page of an obligation file stem, as listed (no slug fold). */
function obligationStemRel(stem: string): string {
return `${BRAIN_OBLIGATIONS_REL}/${stem}.md`;
}
/** The vault-relative page a caller's slug argument names. */
function obligationRel(slug: string): string {
return obligationStemRel(slugify(slug));
}
function toolBrainObligation(
ctx: ServerContext,
args: Record<string, unknown>,
): Record<string, unknown> {
const operation = coerceStr(args, "operation", true)!;
// A record-lane tool works with no vault: its pages are store records then.
const vault = laneVault(ctx);
// Every operation answers at the caller's reach: a page the caller may
// not read is listed, shown, completed and removed exactly as an absent
// one would be, so neither its text nor its existence crosses, and it
// is never written. `undefined` at local reach with the owner gate off.
const readable = readableAtContextReachOrUndefined(ctx);
const withheld = (slug: string): boolean =>
readable !== undefined && !readable(obligationRel(slug));
try {
if (operation === "list") {
const items = listObligations(vault, { overdueOnly: args["overdue"] === true });
// A listed slug is the file's own stem, which need not be slug-shaped,
// so its page is asked about as it is named on disk.
const kept =
readable === undefined ? items : items.filter((o) => readable(obligationStemRel(o.slug)));
return { operation, obligations: kept.map(listItemJson) };
}
if (operation === "add") {
const title = coerceStr(args, "title", true)!;
const cadence = coerceStr(args, "cadence", true)!;
const anchor = coerceStr(args, "anchor", false);
const notes = coerceStr(args, "notes", false);
// `addObligation` refuses a taken slug and never overwrites it; the
// refusal is the one answer that cannot match an absent page's,
// because creating the page would replace the withheld one.
const page = addObligation(vault, {
title,
cadence,
agent: resolveAgentName(ctx.configPath ?? undefined),
...(anchor ? { anchor } : {}),
...(notes ? { notes } : {}),
});
return { operation, obligation: pageJson(page) };
}
const slug = coerceStr(args, "slug", true)!;
if (withheld(slug)) {
if (operation === "show") return { operation, slug, present: false };
if (operation === "done" || operation === "remove") {
throw noObligationError(slugify(slug));
}
}
if (operation === "show") {
const page = showObligation(vault, slug);
if (page === null) return { operation, slug, present: false };
return { operation, present: true, obligation: pageJson(page) };
}
if (operation === "done") {
const date = coerceStr(args, "date", false);
const page = completeObligation(vault, { slug, ...(date ? { date } : {}) });
return { operation, obligation: pageJson(page) };
}
if (operation === "remove") {
const removed = removeObligation(vault, slug);
// The archive name steps past every name already taken in archive/,
// readable or not, so below local reach it is left out of the answer.
if (readable !== undefined) return { operation, slug: removed.slug };
return { operation, slug: removed.slug, archive_path: removed.archivePath };
}
} catch (err) {
// Preserve an already-typed MCPError (e.g. from coerceStr) instead
// of re-wrapping it with a doubled "brain_obligation: " prefix and
// flattening its code. Only wrap unexpected thrown values.
if (err instanceof MCPError) throw err;
throw new MCPError(INVALID_PARAMS, `brain_obligation: ${(err as Error).message}`);
}
throw unknownOperationError(
"brain_obligation operation must be one of: add, done, list, show, remove",
);
}
function coerceEvents(args: Record<string, unknown>): AgendaEventInput[] {
const raw = args["events"];
if (!Array.isArray(raw)) {
throw new MCPError(INVALID_PARAMS, "brain_agenda: 'events' must be an array");
}
return raw.map((entry, index) => {
if (entry === null || typeof entry !== "object") {
throw new MCPError(INVALID_PARAMS, `brain_agenda: event ${index} must be an object`);
}
const obj = entry as Record<string, unknown>;
const start = obj["start"];
const end = obj["end"];
if (typeof start !== "string" || typeof end !== "string") {
throw new MCPError(
INVALID_PARAMS,
`brain_agenda: event ${index} requires string 'start' and 'end'`,
);
}
return {
start,
end,
...(typeof obj["id"] === "string" ? { id: obj["id"] } : {}),
...(typeof obj["title"] === "string" ? { title: obj["title"] } : {}),
...(typeof obj["organizer"] === "string" ? { organizer: obj["organizer"] } : {}),
};
});
}
function snapshotJson(snapshot: AgendaSnapshot): Record<string, unknown> {
return {
counts: {
events: snapshot.counts.events,
conflicts: snapshot.counts.conflicts,
focus_blocks: snapshot.counts.focusBlocks,
external_organizers: snapshot.counts.externalOrganizers,
},
conflicts: snapshot.conflicts,
focus_blocks: snapshot.focusBlocks,
external_organizers: snapshot.externalOrganizers,
events: snapshot.events.map((e) => ({
id: e.id,
title: e.title,
start: e.start,
end: e.end,
organizer: e.organizer,
})),
};
}
function toolBrainAgenda(
_ctx: ServerContext,
args: Record<string, unknown>,
): Record<string, unknown> {
const events = coerceEvents(args);
const focusRaw = args["focus_min_minutes"];
const focusMinMinutes = focusRaw === undefined || focusRaw === null ? 60 : Number(focusRaw);
const workdayStart = coerceStr(args, "workday_start", false);
const workdayEnd = coerceStr(args, "workday_end", false);
if ((workdayStart === null) !== (workdayEnd === null)) {
throw new MCPError(
INVALID_PARAMS,
"brain_agenda: workday_start and workday_end must be given together",
);
}
try {
const snapshot = synthesizeAgenda(events, {
focusMinMinutes,
ownerDomains: coerceStrList(args, "owner_domains"),
...(workdayStart !== null ? { workdayStart, workdayEnd: workdayEnd! } : {}),
});
return snapshotJson(snapshot);
} catch (err) {
// Preserve an already-typed MCPError (e.g. from coerceStr/coerceEvents)
// instead of re-wrapping it with a doubled "brain_agenda: " prefix.
if (err instanceof MCPError) throw err;
throw new MCPError(INVALID_PARAMS, `brain_agenda: ${(err as Error).message}`);
}
}
export const CALENDAR_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_obligation",
kind: "write",
description:
"Recurring obligations with a deterministic cadence-driven next-due date: add, done (advances next_due one interval), list (optionally overdue-only), show, remove. Cadences: daily/weekly/biweekly/monthly/quarterly/yearly/every-<N>-days.",
inputSchema: {
type: "object",
properties: {
operation: {
type: "string",
enum: ["add", "done", "list", "show", "remove"],
description: "Operation to perform.",
},
title: {
type: "string",
minLength: 1,
maxLength: 200,
description: "Obligation title (slugified into the page id) for add.",
},
cadence: {
type: "string",
description:
"Cadence for add: daily | weekly | biweekly | monthly | quarterly | yearly | every-<N>-days.",
},
slug: {
type: "string",
minLength: 1,
maxLength: 200,
description:
"Obligation id for done/show/remove (a title is also accepted and slugified).",
},
anchor: {
type: "string",
description: "First due date (YYYY-MM-DD) for add; defaults to today (UTC).",
},
date: {
type: "string",
description: "Completion date (YYYY-MM-DD) for done; defaults to today (UTC).",
},
notes: { type: "string", maxLength: 4000, description: "Optional page body for add." },
overdue: { type: "boolean", description: "list only: restrict to overdue obligations." },
},
required: ["operation"],
additionalProperties: false,
},
previewBudget: MCP_PREVIEW_BUDGET,
handler: toolBrainObligation,
},
{
name: "brain_agenda",
kind: "read",
description:
"Deterministic agenda synthesis over caller-provided calendar events (the Brain never calls a calendar API): overlap conflicts, free focus blocks (optionally clipped to a workday window), and events organised outside the operator's email domain(s). Pure analysis, no vault writes.",
inputSchema: {
type: "object",
properties: {
events: {
type: "array",
description: "Calendar events to analyse.",
items: {
type: "object",
properties: {
id: { type: "string", description: "Optional caller-side event id, echoed back." },
title: { type: "string", description: "Optional event title." },
start: { type: "string", description: "ISO-8601 start timestamp." },
end: { type: "string", description: "ISO-8601 end timestamp." },
organizer: { type: "string", description: "Organiser email." },
},
required: ["start", "end"],
},
},
focus_min_minutes: {
type: "number",
description: "Minimum free gap (minutes) that counts as a focus block. Default 60.",
},
owner_domains: {
type: "array",
items: { type: "string" },
description: "Operator email domain(s); organisers outside these are flagged external.",
},
workday_start: { type: "string", description: "Workday window start HH:MM (24h, UTC)." },
workday_end: { type: "string", description: "Workday window end HH:MM (24h, UTC)." },
},
required: ["events"],
additionalProperties: false,
},
previewBudget: MCP_PREVIEW_BUDGET,
handler: toolBrainAgenda,
},
]);