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
/**
* `o2b brain tune run|status|reset` (t_ae973491): opt-in self-tuning
* recall. `run` grid-evaluates the bounded parameter space against a
* benchmark dataset, persists the winner to Brain/search/tuning.json,
* and records one `self_tuning` metric; `status` renders the persisted
* choice; `reset` deletes it. Search only honors the tuned state when
* `search_self_tuning_enabled` is on.
*
* Exit codes: 0 on success, 1 on an operational failure, 2 on usage
* errors.
*/
import { readFileSync } from "node:fs";
import { parseRecallBenchmarkDataset } from "../../../core/search/benchmark.ts";
import { tuneRecall } from "../../../core/search/tuning.ts";
import { loadTunedParameters, resetTuning } from "../../../core/search/tuning-store.ts";
import { appendMetric } from "../../../core/brain/metrics.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import { resolveSearchConfig } from "../../../core/search/index.ts";
import { SearchError } from "../../../core/search/types.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { emitNextStep } from "../../advisory-rail.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";
import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
const USAGE =
"usage: o2b brain tune run --dataset <path> [--k N] | status | reset [--vault <path>] [--json]";
export async function cmdBrainTune(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
dataset: { type: "string" },
k: { type: "string" },
json: { type: "boolean" },
});
const asJson = flags["json"] === true;
const action = positional[0];
if (
(action !== "run" && action !== "status" && action !== "reset") ||
positional.length !== 1 ||
(action === "run" && flags["dataset"] === undefined)
) {
process.stderr.write(`${USAGE}\n`);
return 2;
}
const { config, vault } = brainVerbContext(flags);
try {
if (action === "status") {
const tuned = loadTunedParameters(vault);
const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
if (asJson) {
okJson({
enabled: searchConfig.recall.selfTuningEnabled,
tuned,
...(tuned === null ? nextCommandField("recall-tuning-absent") : {}),
});
} else if (tuned === null) {
ok("tune: no valid tuned parameters persisted");
// no-dead-ends, phase 3: this pointer was hand-written beside
// the rail. One mechanism, one line format.
emitNextStep("recall-tuning-absent", { command: "brain", argv, jsonRequested: asJson });
} else {
ok(
`tune: pool x${tuned.poolMultiplier}, depth ${tuned.traversalDepth}, ` +
`learned-weights ${tuned.learnedWeights ? "on" : "off"}, ` +
`expansion ${tuned.expansion ? "on" : "off"} ` +
`(${searchConfig.recall.selfTuningEnabled ? "ACTIVE" : "inactive - enable search_self_tuning_enabled"})`,
);
}
return 0;
}
if (action === "reset") {
const removed = resetTuning(vault);
if (asJson) okJson({ removed });
else ok(removed ? "tune: persisted state removed" : "tune: nothing to remove");
return 0;
}
// run
const k = flags["k"] !== undefined ? Number(flags["k"]) : undefined;
if (k !== undefined && (!Number.isInteger(k) || k < 1)) {
process.stderr.write("brain tune run: --k must be a positive integer\n");
return 2;
}
const datasetPath = flags["dataset"] as string;
let raw: unknown;
try {
raw = JSON.parse(readFileSync(datasetPath, "utf8"));
} catch (exc) {
process.stderr.write(
`brain tune run: cannot read dataset ${datasetPath}: ${(exc as Error).message}\n`,
);
return 2;
}
const dataset = parseRecallBenchmarkDataset(raw);
const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
const now = new Date();
const report = await tuneRecall(searchConfig, dataset, {
transportReach: CLI_TRANSPORT_REACH,
...(k !== undefined ? { k } : {}),
now,
});
try {
appendMetric(vault, {
surface: "self_tuning",
runAt: isoSecond(now),
payload: {
chosen: report.chosen,
evaluated: report.evaluated.length,
best_mrr: Math.max(...report.evaluated.map((e) => e.mrr)),
dataset_hash: report.datasetHash,
},
});
} catch {
// Metrics are observability, not correctness.
}
if (asJson) {
okJson({
chosen: report.chosen,
evaluated: report.evaluated.map((e) => ({
params: e.params,
mrr: e.mrr,
hit_at_k: e.hitAtK,
})),
});
} else {
ok(
`tune: chose pool x${report.chosen.poolMultiplier}, depth ${report.chosen.traversalDepth}, ` +
`learned-weights ${report.chosen.learnedWeights ? "on" : "off"}, ` +
`expansion ${report.chosen.expansion ? "on" : "off"} ` +
`over ${report.evaluated.length} grid points`,
);
ok(
"activate with: search_self_tuning_enabled: true (config) or OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING=1",
);
}
return 0;
} catch (exc) {
if (exc instanceof SearchError && exc.code === "INVALID_INPUT") {
process.stderr.write(`brain tune ${action}: ${exc.message}\n`);
return 2;
}
const message = `tune ${action} failed: ${(exc as Error).message ?? exc}`;
if (asJson) {
okJson({ ok: false, message });
return 1;
}
return fail(message);
}
}