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
/**
* Consolidated analytics dispatcher: timeline, belief evolution, concept synthesis, and attention flows behind the brain_analytics view parameter.
*
* Extracted from the former brain-tools.ts monolith; registration
* happens through the aggregator, which preserves the public
* BRAIN_TOOLS surface.
*/
import {
INGEST_DEDUP_SURFACES,
summarizeIngestDedup,
type IngestDedupSurface,
} from "../../core/brain/dedup-telemetry.ts";
import { buildConceptCluster } from "../../core/brain/link-graph/concept-cluster.ts";
import { gatedOwnerScopeView } from "../../core/brain/owner-scope-view.ts";
import { buildTimelineIndex } from "../../core/brain/temporal/build-index.ts";
import { selectEvents } from "../../core/brain/temporal/select-events.ts";
import { buildBeliefEvolution } from "../../core/brain/temporal/belief-evolution.ts";
import { isBrainLogEventKind, type BrainLogEventKind } from "../../core/brain/types.ts";
import {
evaluateAttentionFlow,
listAttentionFlows,
renderAttentionFlow,
} from "../../core/brain/attention-flows.ts";
import { normaliseWikilinkTarget } from "../../core/brain/wikilink.ts";
import { pageSlice } from "../../core/brain/offset-cursor.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { cursorOffsetArg, CURSOR_SCHEMA } from "./pagination.ts";
import {
coerceIsoTimestampOrDate,
coercePositiveInteger,
dispatchByView,
localizeEnvelope,
requiredStringArg,
} from "./shared.ts";
import { unknownOperationError } from "../coerce.ts";
import type { ArtifactRef } from "../../core/brain/artifact-ref-view.ts";
import { eventsAtReach, recordReadable, recordRefs, requestRefView } from "./reach-events.ts";
function coerceEventKind(tool: string, raw: unknown): BrainLogEventKind | undefined {
if (raw === undefined || raw === null) return undefined;
if (typeof raw !== "string") {
throw new MCPError(INVALID_PARAMS, `${tool}: kind must be a string`);
}
if (!isBrainLogEventKind(raw)) {
throw new MCPError(INVALID_PARAMS, `${tool}: kind must be a known BrainLogEventKind`);
}
return raw;
}
/**
* `brain_timeline` - frozen chronological list of events filtered by
* any combination of `pref_id`, `topic`, `kind`, `since`, `until`,
* `limit`. Pure read.
*/
async function toolBrainTimeline(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const prefId = typeof args["pref_id"] === "string" ? args["pref_id"] : undefined;
const topic = typeof args["topic"] === "string" ? args["topic"] : undefined;
const kind = coerceEventKind("brain_timeline", args["kind"]);
const since = coerceIsoTimestampOrDate("brain_timeline", "since", args["since"]);
const until = coerceIsoTimestampOrDate("brain_timeline", "until", args["until"]);
const limit = coercePositiveInteger("brain_timeline", "limit", args["limit"]);
const index = buildTimelineIndex(ctx.vault, {
...(since !== undefined ? { since } : {}),
...(until !== undefined ? { until } : {}),
});
const events = selectEvents(index, {
...(prefId !== undefined ? { prefId } : {}),
...(topic !== undefined ? { topic } : {}),
...(kind !== undefined ? { kind } : {}),
...(since !== undefined ? { since } : {}),
...(until !== undefined ? { until } : {}),
});
// A timeline row names the preference the event was about, its topic,
// and the file the event was read from (a-label-is-not-a-boundary,
// U3). Filtered BEFORE the limit and before `total`, so the count is
// the visible one - a total that still included the hidden rows would
// leak their number.
//
// The same holds one rule over at the caller's reach: an event naming a
// record the caller cannot read (under its pref- or ret- spelling) is
// dropped, and a dream shared with one is kept while a transition it
// names is readable.
const view = gatedOwnerScopeView(ctx.vault, ctx.agentName);
const visible = eventsAtReach(
requestRefView(ctx),
view.keep(events, (ev) => [ev.source.path, ev.prefId, ev.artifact]),
);
// The page is cut here over the full visible set, so `total` stays the
// exact count across pages and `next_cursor` continues the walk (null
// when exhausted). Absent `limit`, the whole window is one page.
const page = pageSlice(
visible,
cursorOffsetArg("brain_analytics", args),
limit ?? Math.max(visible.length, 1),
);
return {
vault_path: vaultPathField(ctx),
window: index.window,
total: page.total,
events: page.items.map((ev) => ({
at: ev.at,
kind: ev.kind,
source: ev.source,
...(ev.prefId !== undefined ? { pref_id: ev.prefId } : {}),
...(ev.topic !== undefined ? { topic: ev.topic } : {}),
...(ev.result !== undefined ? { result: ev.result } : {}),
...(ev.artifact !== undefined ? { artifact: ev.artifact } : {}),
...(ev.reason !== undefined ? { reason: ev.reason } : {}),
...(ev.text !== undefined ? { text: ev.text } : {}),
})),
next_cursor: page.next_cursor,
};
}
/**
* `brain_belief_evolution` - per-pref / per-topic chronological story:
* status transitions, evidence rollup with running counts, and
* retirement chain.
*/
async function toolBrainBeliefEvolution(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const prefIdRaw = args["pref_id"];
const topicRaw = args["topic"];
const hasPref = typeof prefIdRaw === "string" && prefIdRaw.trim().length > 0;
const hasTopic = typeof topicRaw === "string" && topicRaw.trim().length > 0;
if (hasPref === hasTopic) {
throw new MCPError(
INVALID_PARAMS,
"brain_analytics view=belief_evolution: exactly one of pref_id or topic is required",
);
}
const target = hasPref
? { prefId: (prefIdRaw as string).trim() }
: { topic: (topicRaw as string).trim() };
// Every row is derived from the index and never passes `eventAtReach`,
// so below local reach a private event must not enter the index at all:
// its evidence row or transition would name only readable records.
const refs = requestRefView(ctx);
const index = buildTimelineIndex(ctx.vault, { withholdsPrivate: refs.withholdsPrivate === true });
const evo = buildBeliefEvolution(index, ctx.vault, target);
// A topic target fans out to every pref/ret carrying that topic, so
// one `topic` argument reaches artifacts the caller never named
// (a-label-is-not-a-boundary, U3). Every row names its subject: a
// transition by `prefId` and by the wikilink the dream summary used,
// an evidence row by `prefId` and by the `artifact` it was applied to,
// a retirement by its whole supersession chain.
//
// At the caller's reach every row is asked under each spelling its
// records answer to, and a pref_id target the caller cannot read is
// answered as an absent one: no row at all.
const view = gatedOwnerScopeView(ctx.vault, ctx.agentName);
const targetShown = !hasPref || recordReadable(refs, (prefIdRaw as string).trim());
const shown = <T>(
rows: ReadonlyArray<T>,
ownerRefs: (row: T) => ReadonlyArray<ArtifactRef>,
reachRefs: (row: T) => ReadonlyArray<ArtifactRef>,
): ReadonlyArray<T> => (targetShown ? refs.keep(view.keep(rows, ownerRefs), reachRefs) : []);
return {
vault_path: vaultPathField(ctx),
target: evo.target,
transitions: shown(
evo.transitions,
(t) => [t.prefId, t.link],
(t) => [t.link, ...recordRefs(t.prefId)],
),
evidence: shown(
evo.evidence,
(e) => [e.prefId, e.artifact],
(e) => [e.artifact, ...recordRefs(e.prefId)],
),
retirements: shown(
evo.retirements,
(r) => [r.prefId, r.retiredBy, r.supersededBy, r.supersedes],
(r) => [
...recordRefs(r.prefId),
...recordRefs(r.retiredBy),
...recordRefs(r.supersededBy),
...recordRefs(r.supersedes),
],
),
generated_at: evo.generatedAt,
};
}
/**
* Concept-scoped cluster envelope: target + all linkers (depth-1)
* plus optionally unlinked mentions. Pure assembler; no LLM call.
*/
async function toolBrainConceptSynthesis(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const idRaw = args["id"];
if (typeof idRaw !== "string" || idRaw.trim().length === 0) {
throw new MCPError(
INVALID_PARAMS,
"brain_analytics view=concept_synthesis: id must be a non-empty string",
);
}
const includeUnlinkedRaw = args["include_unlinked"];
let includeUnlinked = false;
if (includeUnlinkedRaw !== undefined && includeUnlinkedRaw !== null) {
if (typeof includeUnlinkedRaw !== "boolean") {
throw new MCPError(
INVALID_PARAMS,
"brain_analytics view=concept_synthesis: include_unlinked must be a boolean",
);
}
includeUnlinked = includeUnlinkedRaw;
}
const targetId = normaliseWikilinkTarget(idRaw);
// `linkers[].source` names every artifact pointing at the target and
// `unlinkedMentions[]` carries a VERBATIM line of the mentioning
// page's body (a-label-is-not-a-boundary, U3). Both producers already
// take the scope; passing it is the whole fix.
// At the caller's reach a linker or a mention whose source page the
// caller cannot read is dropped, and a target it cannot read (under its
// pref- or ret- spelling) is answered as an absent one: its own id as
// the title and an empty cluster. A private log event links nothing.
const refs = requestRefView(ctx);
const cluster = buildConceptCluster(ctx.vault, targetId, {
includeUnlinked,
ownerScope: gatedOwnerScopeView(ctx.vault, ctx.agentName).scope,
withholdsPrivate: refs.withholdsPrivate === true,
});
const targetShown = recordReadable(refs, cluster.targetId);
return {
vault_path: vaultPathField(ctx),
target_id: cluster.targetId,
target_title: targetShown ? cluster.targetTitle : cluster.targetId,
linkers: targetShown ? refs.keep(cluster.linkers, (l) => [l.source]) : [],
unlinked_mentions: targetShown ? refs.keep(cluster.unlinkedMentions, (m) => [m.source]) : [],
generated_at: cluster.generatedAt,
};
}
// ----- brain_moc_audit (v0.10.17) ------------------------------------------
async function toolBrainAttentionFlows(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const operation = requiredStringArg("brain_attention_flows", args, "operation");
if (operation === "list") {
const flows = listAttentionFlows(ctx.vault);
return { total: flows.length, flows };
}
if (operation === "evaluate") {
const flowId = requiredStringArg("brain_attention_flows", args, "flow_id");
const report = evaluateAttentionFlow(ctx.vault, flowId);
return { ...report };
}
if (operation === "render") {
const flowId = requiredStringArg("brain_attention_flows", args, "flow_id");
return {
flow_id: flowId,
text: renderAttentionFlow(ctx.vault, flowId),
};
}
throw unknownOperationError(
"brain_analytics view=attention_flows: operation must be one of list|evaluate|render",
);
}
/**
* `view=dedup` - the persisted exact-hash ingest dedup trend.
*
* Every number here counts an item DROPPED on a sha-256 collision. The
* semantic dedup detectors are proposal-only nomination systems that never
* drop anything, so this lens deliberately publishes no semantic figure -
* see `src/core/brain/dedup-telemetry.ts`.
*/
async function toolBrainDedup(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const surface = args["surface"];
if (surface !== undefined && surface !== null) {
if (
typeof surface !== "string" ||
!(INGEST_DEDUP_SURFACES as ReadonlyArray<string>).includes(surface)
) {
throw new MCPError(
INVALID_PARAMS,
`brain_analytics view=dedup: surface must be one of ${INGEST_DEDUP_SURFACES.join(", ")}`,
);
}
}
const since = coerceIsoTimestampOrDate("brain_analytics", "since", args["since"]);
const until = coerceIsoTimestampOrDate("brain_analytics", "until", args["until"]);
const summary = summarizeIngestDedup(ctx.vault, {
...(typeof surface === "string" ? { surface: surface as IngestDedupSurface } : {}),
...(since !== undefined ? { since } : {}),
...(until !== undefined ? { until } : {}),
});
// `by_source[].ref` is the one field here with a per-artifact subject:
// "a session id, or a vault-relative note path - whatever the run keys
// provenance by" (`dedup-telemetry.ts`), and a note path is
// owner-taggable (a-label-is-not-a-boundary, U3). The totals and the
// per-run trend beside it are folds over ingest RUNS with no artifact
// in them, so they stay as measured.
const view = gatedOwnerScopeView(ctx.vault, ctx.agentName);
return {
vault_path: vaultPathField(ctx),
...summary,
by_source: view.keep(summary.by_source, (row) => [row.ref]),
};
}
const ANALYTICS_VIEW_HANDLERS: Readonly<
Record<string, (ctx: ServerContext, args: Record<string, unknown>) => Promise<unknown> | unknown>
> = Object.freeze({
timeline: toolBrainTimeline,
attention_flows: toolBrainAttentionFlows,
belief_evolution: toolBrainBeliefEvolution,
concept_synthesis: toolBrainConceptSynthesis,
dedup: toolBrainDedup,
});
async function toolBrainAnalytics(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<unknown> {
// attention_flows requires an `operation`; the consolidated surface
// defaults it to `list` so `{view}` alone is valid.
const withDefaults = args["view"] === "attention_flows" ? { operation: "list", ...args } : args;
return localizeEnvelope(ctx, await dispatchByView(ANALYTICS_VIEW_HANDLERS, ctx, withDefaults));
}
export const ANALYTICS_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_analytics",
// Write-mode-dominant (tool-contract.ts), not "read": every
// attention_flows operation lists the flow recipes first, and
// `listAttentionFlows` seeds `Brain/attention-flows/open-loops.md`
// through `ensureDefaultAttentionFlows` (mkdir + frontmatter write,
// under the vault-identity write guard) whenever the vault lacks it.
// A fresh vault therefore gets files written by a "read" view.
kind: "write",
previewBudget: MCP_PREVIEW_BUDGET,
description:
"Brain analytics, one tool for every lens: view=timeline (event history), attention_flows (seeds its default recipe when missing), belief_evolution, concept_synthesis, or dedup (exact-hash ingest dedup trend). Replaces the per-lens analytics tools.",
inputSchema: {
type: "object",
properties: {
view: {
type: "string",
enum: ["timeline", "attention_flows", "belief_evolution", "concept_synthesis", "dedup"],
description: "Which analytics lens to run.",
},
pref_id: {
type: "string",
description: "timeline / belief_evolution: target preference id.",
},
topic: { type: "string", description: "timeline / belief_evolution: target topic slug." },
kind: { type: "string", description: "view=timeline: restrict to one event kind." },
since: { type: "string", description: "view=timeline / dedup: inclusive ISO lower bound." },
until: { type: "string", description: "view=timeline / dedup: exclusive ISO upper bound." },
surface: {
type: "string",
enum: ["session_lifecycle", "scan_inline", "session_import"],
description: "view=dedup: restrict the trend to one ingest surface.",
},
limit: { type: "integer", minimum: 1, description: "view=timeline: max events returned." },
cursor: CURSOR_SCHEMA,
id: { type: "string", description: "view=concept_synthesis: target id (e.g. pref-foo)." },
include_unlinked: {
type: "boolean",
description: "view=concept_synthesis: include raw-text mentions (default false).",
},
operation: {
type: "string",
enum: ["list", "evaluate", "render"],
description: "view=attention_flows: operation, default list.",
},
flow_id: {
type: "string",
description: "view=attention_flows: flow id for evaluate/render.",
},
},
required: ["view"],
additionalProperties: false,
},
handler: toolBrainAnalytics,
},
]);