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
/**
* Research-report tool (Knowledge Provenance suite).
*
* The agent pulls N sources and synthesizes findings; it submits the title,
* the consulted sources, and the findings (each citing the source that flagged
* it). OSB runs no model - it validates the citation contract and writes a
* dated, cited report page into the vault. A finding with no source, or one
* citing an unconsulted source, is rejected as INVALID_PARAMS.
*/
import {
writeResearchReport,
ResearchValidationError,
parseResearchReportInput,
} from "../../core/brain/research/research.ts";
import { ResponseShapeError } from "../../core/brain/response-shape.ts";
import { resolveAgentName } from "../../core/config.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { coerceStr } from "../coerce.ts";
import { readableAtContextReach } from "./reach-readable.ts";
import { wrapToolErrors } from "./shared.ts";
const TOOL = "brain_research_report";
async function toolBrainResearchReport(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const agentArg = coerceStr(args, "agent", false);
const agent =
agentArg && agentArg.trim().length > 0
? agentArg
: resolveAgentName(ctx.configPath ?? undefined);
return wrapToolErrors(TOOL, [ResearchValidationError, ResponseShapeError], async () => {
// Shape first: the payload is validated before the citation contract is
// evaluated, so a malformed finding aborts the report unwritten.
const input = parseResearchReportInput(args);
// Scopes answer at the caller's reach: a page the caller may not read
// is reported exactly as an absent one.
const res = writeResearchReport(ctx.vault, input, {
agent,
now: new Date(),
readable: readableAtContextReach(ctx),
});
return {
report_path: res.reportPath,
created: res.created,
finding_count: res.findingCount,
// One scope per consulted source, in the caller's `sources` order.
capture_scopes: [...res.captureScopes],
};
});
}
export const RESEARCH_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: TOOL,
kind: "write",
description:
"Write a dated, cited research report. Supply `title`, consulted `sources`, and `findings` (each citing its source). OSB rejects uncited findings, then writes one report page per date+title (idempotent). OSB runs no model.",
inputSchema: {
type: "object",
properties: {
title: { type: "string", description: "Report title (also the page slug)." },
sources: {
type: "array",
items: { type: "string" },
description: "Every source consulted (identifiers or wikilinks).",
},
findings: {
type: "array",
description: "Findings, each citing the source(s) that flagged it.",
items: {
type: "object",
properties: {
statement: { type: "string", description: "The finding text." },
sources: {
type: "array",
items: { type: "string" },
description: "Sources (a subset of `sources`) that flagged this finding.",
},
},
required: ["statement", "sources"],
additionalProperties: false,
},
},
agent: {
type: "string",
description: "Optional agent identity override; defaults to the server-resolved name.",
},
},
required: ["title", "sources", "findings"],
additionalProperties: false,
},
handler: toolBrainResearchReport,
},
]);