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
/**
* Procedural memory: skill proposals, procedural reconcile, recurrence diagnostics, and the procedural graph.
*
* Extracted from the former brain-tools.ts monolith; registration
* happens through the aggregator, which preserves the public
* BRAIN_TOOLS surface.
*/
import { join } from "node:path";
import {
acceptSkillProposal,
discardUnreadableSkillAcceptJournals,
learnSkillProposals,
listPendingSkillProposals,
pendingSkillProposalPatternKind,
readSkillRewriteStatus,
recoverSkillProposalAccepts,
rejectSkillProposal,
resolveSkillProposalEvidence,
SCORED_REWRITE_PATTERN_KIND,
type SkillContractInput,
} from "../../core/brain/skill-proposals.ts";
import { commitSkillPageDraft, planSkillPageDrafts } from "../../core/brain/skill-page-drafts.ts";
import { deriveSkillUsage } from "../../core/brain/skill-usage.ts";
import { resolveSkillsDir } from "../../core/config.ts";
import {
listProceduralMemory,
markProceduralMemoryUsed,
recordProceduralOutcome,
rankProceduralMemory,
reconcileProceduralMemory,
} from "../../core/brain/procedural-memory.ts";
import { readProceduralGraph, rebuildProceduralGraph } from "../../core/brain/procedural-graph.ts";
import { readProceduralHints, rebuildProceduralHints } from "../../core/brain/procedural-hints.ts";
import {
applyRecurrenceEvidence,
getRecurrenceEntry,
listRecurrenceEntries,
purgeRecurrenceSource,
} from "../../core/brain/recurrence.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { contextReach } from "../tool-contract.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { coerceStrList, unknownOperationError } from "../coerce.ts";
import { coercePositiveInteger, optionalStringArg, requiredStringArg } from "./shared.ts";
import { readableAtContextReach } from "./reach-readable.ts";
// Record-lane tools: with no vault their pages are store records (task 2.10 WP6).
import { laneVault } from "./lane-vault.ts";
async function toolBrainSkillProposals(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const operation = requiredStringArg("brain_skill_proposals", args, "operation");
if (operation === "learn") {
const minSupport = coercePositiveInteger(
"brain_skill_proposals",
"min_support",
args["min_support"],
);
const result =
minSupport !== undefined
? learnSkillProposals(laneVault(ctx), { minSupport })
: learnSkillProposals(laneVault(ctx));
return { ...result };
}
if (operation === "list") {
const proposals = listPendingSkillProposals(laneVault(ctx));
return { total: proposals.length, proposals };
}
if (operation === "accept") {
const slug = requiredStringArg("brain_skill_proposals", args, "slug");
refuseScoredRewriteAccept(laneVault(ctx), slug);
const note = optionalStringArg("brain_skill_proposals", args, "note");
const contract = readSkillContract(args);
// Resolved from THIS server's config chain: a `mature_page` accept
// materializes a SKILL.md into whichever skills root it names, and the
// core cannot know which chain the server was started with.
const skillsRoot = resolveSkillsDir(ctx.configPath ?? undefined);
const reviewed = acceptSkillProposal(laneVault(ctx), slug, {
...(note ? { note } : {}),
...(contract ? { contract } : {}),
...(skillsRoot !== null ? { skillsRoot } : {}),
});
return { ...reviewed };
}
if (operation === "page_candidates") {
// Read-only: which mature vault pages deserve a skill, each with its
// own needs-llm-step envelope, plus every page the gate turned down
// with the reason it did.
const skillsDir = resolveSkillsDir(ctx.configPath ?? undefined);
const report = planSkillPageDrafts(laneVault(ctx), {
now: new Date(),
...(ctx.repoRoot ? { repoRoot: ctx.repoRoot } : {}),
...(skillsDir !== null ? { skillsDir } : {}),
});
// `planSkillPageDrafts` walks with `MAINTENANCE_LANE_REACH`, which is
// right for a plan that has to see the whole vault it is proposing
// over - and wrong to hand to a caller unfiltered, because both lists
// report a page's path and title and `skipped` adds a `detail` about
// it. The rule is asked here, over what the caller is told.
//
// `pages_scanned` is recomputed from the visible lists for the same
// reason `brain_hygiene` recomputes its counts: a corpus size taken
// before the filter states how many pages were withheld.
const view = reachView(laneVault(ctx), contextReach(ctx));
const admitted = report.admitted.filter((c) => view.visible(c.path));
const skipped = report.skipped.filter((s) => view.visible(s.path));
return {
generated_at: report.generatedAt,
pages_scanned: view.filtersNothing ? report.pagesScanned : admitted.length + skipped.length,
admitted: admitted.map((c) => ({
path: c.path,
title: c.title,
tier: c.tier,
lifecycle: c.lifecycle,
confidence: c.confidence,
reuse_score: c.reuseScore,
reuse_observations: c.reuseObservations,
llm_step: c.llmStep,
})),
skipped: skipped.map((s) => ({
path: s.path,
title: s.title,
reason: s.reason,
detail: s.detail,
})),
};
}
if (operation === "page_draft") {
const page = requiredStringArg("brain_skill_proposals", args, "page");
const result = commitSkillPageDraft(laneVault(ctx), page, args["draft"], { now: new Date() });
return { ...result };
}
if (operation === "evidence") {
const slug = requiredStringArg("brain_skill_proposals", args, "slug");
return { ...resolveSkillProposalEvidence(laneVault(ctx), slug) };
}
if (operation === "reject") {
const slug = requiredStringArg("brain_skill_proposals", args, "slug");
const note = requiredStringArg("brain_skill_proposals", args, "note");
const reviewed = rejectSkillProposal(laneVault(ctx), slug, { note });
return { ...reviewed };
}
if (operation === "recover") {
// The accept sequence's write-ahead journal was recoverable in the
// library and reachable from no tool, so an agent whose accept
// crashed had nothing to call. Both refusals it can raise carry the
// file and the exit in their message; they surface as errors here
// rather than as a result field, because neither is a state this
// operation completed.
const discarded =
args["discard_unreadable"] === true
? discardUnreadableSkillAcceptJournals(laneVault(ctx))
: [];
const recovered = recoverSkillProposalAccepts(laneVault(ctx));
return { discarded, recovered, total: recovered.length };
}
if (operation === "usage") {
// Per-skill invocation telemetry (t_56a12bde): deterministic counts
// derived from skill_invoked continuity records, distinct from proposing
// or ranking. Real usage evidence for the dream/synthesis pass.
// Each row also carries `offerAttributedCount` (t_ccb05134) - how many of
// those invocations cited the offer they came from. The command-line
// surface prints the same figure as `from_offer=`. The remainder are not
// unattributed-by-error: most runtimes' skill calls follow no offer.
const usage = deriveSkillUsage(laneVault(ctx));
return { total: usage.length, usage };
}
throw unknownOperationError(
"brain_skill_proposals: operation must be one of " +
"learn|list|accept|reject|recover|usage|evidence|page_candidates|page_draft",
);
}
/**
* Read the optional execution contract from an accept payload. Returns
* undefined when the caller supplied none, so the accept path stays
* byte-identical to a pre-contract acceptance.
*/
function readSkillContract(args: Record<string, unknown>): SkillContractInput | undefined {
const prerequisites = coerceStrList(args, "prerequisites");
const rollback = coerceStrList(args, "rollback");
const sideEffects = coerceStrList(args, "side_effects");
const verification = coerceStrList(args, "verification");
if (
prerequisites.length === 0 &&
rollback.length === 0 &&
sideEffects.length === 0 &&
verification.length === 0
) {
return undefined;
}
return { prerequisites, rollback, sideEffects, verification };
}
/**
* Refuse the one accept the design keeps out of the agent's reach
* (review security M1c): a `scored_rewrite` proposal OVERWRITES an
* incumbent SKILL.md, and its acceptance is the operator's step - MCP
* proposes, the human accepts on the command line. The sibling read tool
* `brain_skill_rewrite_status` states this in its own description; this
* guard is what makes it true for the whole surface family.
*
* Mined, declared and mature-page accepts are unchanged: they create or
* fill vault pages, they never overwrite, and the calling agent has always
* been able to write those trees directly.
*/
function refuseScoredRewriteAccept(vault: string, slug: string): void {
if (pendingSkillProposalPatternKind(vault, slug) !== SCORED_REWRITE_PATTERN_KIND) return;
throw new MCPError(
INVALID_PARAMS,
`brain_skill_proposals: '${slug}' is a ${SCORED_REWRITE_PATTERN_KIND} proposal, whose accept ` +
"OVERWRITES an incumbent skill; MCP never accepts a benchmark-gated rewrite - the " +
"operator reviews and accepts it on the command line: o2b brain skill-proposals accept",
);
}
async function toolBrainProceduralMemory(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const operation = requiredStringArg("brain_procedural_memory", args, "operation");
// An entry names its page's path, title and frontmatter lists, so a page
// the caller may not read at its reach is answered as an absent one: left
// out of every count and list, and an unknown id to the two mark
// operations, refused before anything is written.
const readable = readableAtContextReach(ctx);
const unknownId = (id: string): boolean => {
const entry = listProceduralMemory(laneVault(ctx)).find((e) => e.id === id);
return entry === undefined || !readable(entry.sourcePath);
};
if (operation === "reconcile") {
const roots = coerceStrList(args, "roots");
const effectiveRoots =
roots.length > 0
? roots
: [
join(laneVault(ctx), "Brain", "procedures"),
join(laneVault(ctx), "skills"),
join(laneVault(ctx), "runbooks"),
];
return {
...reconcileProceduralMemory(laneVault(ctx), { roots: effectiveRoots, include: readable }),
};
}
if (operation === "list") {
const entries = listProceduralMemory(laneVault(ctx)).filter((e) => readable(e.sourcePath));
// Opt-in success-rate ranking (t_703f7b18); default order unchanged.
const ordered = args["ranked"] === true ? rankProceduralMemory(entries) : entries;
return { total: ordered.length, entries: ordered };
}
if (operation === "mark_used") {
const id = requiredStringArg("brain_procedural_memory", args, "id");
const updated = unknownId(id) ? null : markProceduralMemoryUsed(laneVault(ctx), id);
if (!updated) {
throw new MCPError(INVALID_PARAMS, `brain_procedural_memory: unknown entry id: ${id}`);
}
return { ...updated };
}
if (operation === "mark_outcome") {
const id = requiredStringArg("brain_procedural_memory", args, "id");
const outcome = requiredStringArg("brain_procedural_memory", args, "outcome");
if (outcome !== "success" && outcome !== "failure") {
throw new MCPError(
INVALID_PARAMS,
"brain_procedural_memory: outcome must be 'success' or 'failure'",
);
}
const updated = unknownId(id) ? null : recordProceduralOutcome(laneVault(ctx), id, outcome);
if (!updated) {
throw new MCPError(INVALID_PARAMS, `brain_procedural_memory: unknown entry id: ${id}`);
}
return { ...updated };
}
throw unknownOperationError(
"brain_procedural_memory: operation must be one of reconcile|list|mark_used|mark_outcome",
);
}
async function toolBrainRecurrence(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const operation = requiredStringArg("brain_recurrence", args, "operation");
if (operation === "list") {
const entries = listRecurrenceEntries(laneVault(ctx));
return { total: entries.length, entries };
}
if (operation === "show") {
const contentHash = requiredStringArg("brain_recurrence", args, "content_hash");
const entry = getRecurrenceEntry(laneVault(ctx), contentHash);
if (!entry) {
throw new MCPError(INVALID_PARAMS, `brain_recurrence: unknown content hash: ${contentHash}`);
}
return { ...entry };
}
if (operation === "learn" || operation === "forget") {
const contentHash = requiredStringArg("brain_recurrence", args, "content_hash");
const scope = requiredStringArg("brain_recurrence", args, "scope");
const sourceId = requiredStringArg("brain_recurrence", args, "source_id");
const entry = applyRecurrenceEvidence(laneVault(ctx), {
contentHash,
scope,
sourceId,
action: operation,
});
return { operation, entry };
}
if (operation === "purge_source") {
const sourceId = requiredStringArg("brain_recurrence", args, "source_id");
purgeRecurrenceSource(laneVault(ctx), sourceId);
return { ok: true, source_id: sourceId };
}
throw unknownOperationError(
"brain_recurrence: operation must be one of list|show|learn|forget|purge_source",
);
}
async function toolBrainSkillRewriteStatus(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const skillName = requiredStringArg("brain_skill_rewrite_status", args, "skill_name");
const status = readSkillRewriteStatus(laneVault(ctx), skillName);
return {
skill: status.skill,
receipt: status.receipt,
grades: status.grades,
unreadable_grades: status.unreadable_grades,
pending_rewrite_slug: status.pending_rewrite_slug,
};
}
async function toolBrainProceduralGraph(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const operation = requiredStringArg("brain_procedural_graph", args, "operation");
if (operation === "rebuild") {
const graph = rebuildProceduralGraph(laneVault(ctx));
const hints = rebuildProceduralHints(laneVault(ctx), { graph });
return {
operation,
graph: {
nodes: graph.nodes.length,
edges: graph.edges.length,
generated_at: graph.generated_at,
},
hints: {
entries: hints.entries.length,
generated_at: hints.generated_at,
},
};
}
if (operation === "show") {
const graph = readProceduralGraph(laneVault(ctx));
if (!graph) {
throw new MCPError(INVALID_PARAMS, "brain_procedural_graph: graph projection not found");
}
return { ...graph };
}
if (operation === "hints") {
const hints = readProceduralHints(laneVault(ctx));
if (!hints) {
throw new MCPError(INVALID_PARAMS, "brain_procedural_graph: hints projection not found");
}
return { ...hints };
}
throw unknownOperationError(
"brain_procedural_graph: operation must be one of rebuild|show|hints",
);
}
export const PROCEDURE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_skill_proposals",
kind: "write",
description:
"Skill proposals: learn, list, accept, reject; recover abandoned accepts; usage counts; evidence against the outcome ledger. page_candidates gates mature vault pages (tier, lifecycle, confidence, reuse; skips ones a skill covers), one envelope each; page_draft stages the returned draft.",
inputSchema: {
type: "object",
properties: {
operation: {
type: "string",
enum: [
"learn",
"list",
"accept",
"reject",
"recover",
"usage",
"evidence",
"page_candidates",
"page_draft",
],
description: "Tool operation.",
},
discard_unreadable: {
type: "boolean",
description:
"recover only: delete accept-journal markers that cannot be parsed. Off by default: removing one unblocks accepting without resolving the sequence it marked.",
},
min_support: {
type: "integer",
minimum: 1,
description: "Optional minimum evidence support for learn.",
},
slug: {
type: "string",
description:
"Proposal slug for accept/reject/evidence. scored_rewrite accepts are refused here: " +
"the operator accepts them on the command line.",
},
note: {
type: "string",
description: "Optional review note; required for reject.",
},
prerequisites: {
type: "array",
items: { type: "string" },
description: "accept only: conditions that must hold before the procedure runs.",
},
rollback: {
type: "array",
items: { type: "string" },
description: "accept only: steps that undo the procedure.",
},
side_effects: {
type: "array",
items: { type: "string" },
description: "accept only: state the procedure changes outside its own output.",
},
verification: {
type: "array",
items: { type: "string" },
description: "accept only: checks that confirm the procedure worked.",
},
page: {
type: "string",
description: "page_draft only: vault-relative path of the page the draft came from.",
},
draft: {
type: "object",
description: "page_draft only: the SKILL.md draft written for that page.",
properties: {
name: {
type: "string",
description: "Skill directory name: lowercase letters, digits, single hyphens.",
},
description: {
type: "string",
description: "One line naming when an agent should reach for this skill.",
},
triggers: {
type: "array",
items: { type: "string" },
description: "Keywords a matcher scores the skill on; each must be non-empty.",
},
body: {
type: "string",
description: "The SKILL.md body: imperative and self-contained.",
},
},
required: ["name", "description", "triggers", "body"],
additionalProperties: false,
},
},
required: ["operation"],
additionalProperties: false,
},
handler: toolBrainSkillProposals,
},
{
name: "brain_skill_rewrite_status",
kind: "read",
description:
"Read-only rewrite-lane status: the frozen benchmark receipt and whether the task set still verifies, completed gate runs' verdicts and rates, and any staged rewrite awaiting a human accept. MCP never accepts or scores.",
inputSchema: {
type: "object",
properties: {
skill_name: {
type: "string",
description: "Skill directory name: lowercase letters, digits, single hyphens.",
},
},
required: ["skill_name"],
additionalProperties: false,
},
handler: toolBrainSkillRewriteStatus,
},
{
name: "brain_procedural_memory",
kind: "write",
description:
"Reconcile/list procedural memory and update the usage + outcome sidecar (reconcile, list, mark_used, mark_outcome). list accepts ranked:true to order by validated success rate.",
inputSchema: {
type: "object",
properties: {
operation: {
type: "string",
enum: ["reconcile", "list", "mark_used", "mark_outcome"],
description: "Tool operation.",
},
roots: {
type: "array",
items: { type: "string" },
description: "Optional root directories for reconcile.",
},
id: {
type: "string",
description: "Procedural entry id for mark_used / mark_outcome.",
},
outcome: {
type: "string",
enum: ["success", "failure"],
description: "Host-reported result for mark_outcome.",
},
ranked: {
type: "boolean",
description: "list only: order entries by validated success rate.",
},
},
required: ["operation"],
additionalProperties: false,
},
handler: toolBrainProceduralMemory,
},
{
name: "brain_recurrence",
kind: "write",
description:
"Inspect and update recurrence/support diagnostics (list, show, learn, forget, purge_source).",
inputSchema: {
type: "object",
properties: {
operation: {
type: "string",
enum: ["list", "show", "learn", "forget", "purge_source"],
description: "Tool operation.",
},
content_hash: {
type: "string",
description: "Content hash for show/learn/forget.",
},
scope: {
type: "string",
description: "Scope for learn/forget.",
},
source_id: {
type: "string",
description: "Source id for learn/forget/purge_source.",
},
},
required: ["operation"],
additionalProperties: false,
},
handler: toolBrainRecurrence,
},
{
name: "brain_procedural_graph",
kind: "write",
description:
"Rebuild/show procedural graph projection and prospective hint projection (rebuild, show, hints).",
inputSchema: {
type: "object",
properties: {
operation: {
type: "string",
enum: ["rebuild", "show", "hints"],
description: "Tool operation.",
},
},
required: ["operation"],
additionalProperties: false,
},
handler: toolBrainProceduralGraph,
},
]);