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 extract-signals <session-ref>` (t_1dace26d): mine durable
* taste signals out of an already-imported session's user turns.
*
* Two phases through one verb. Without a payload the verb is read-only and
* prints the mining plan plus the single needs-llm-step envelope the
* calling agent answers. With `--payload` / `--payload-file` it validates
* that answer and writes the accepted items as speculative inbox signals.
* OSB runs no model on either path.
*
* Every commit records its outcome in the session mining ledger over the
* session's current mined turns. The plan records the hash of the turns it
* offered as a pending survey, so a barren commit leaves the zero-yield
* tombstone without any relay - but only while the session still holds
* the surveyed turns; turns imported after the plan withhold it, and the
* commit says so. `--surveyed-turns-hash` optionally passes the answered
* plan's `surveyed_turns_hash` back as a check: a malformed value refuses
* the commit, and a value the session no longer matches writes the
* signals but no mining record, and says so.
*
* A session already mined at its current content that yielded nothing
* accepted carries a tombstone in the session mining ledger; its plan phase
* returns the recorded breakdown instead of an envelope (reason
* `mining_tombstone`), and `--force` bypasses that gate for the one plan
* call it is given to. A commit that succeeds but cannot record its
* zero-yield tombstone still succeeds, and names the ledger failure.
*
* Exit codes: 0 on success, 1 on an operational failure or a refused
* payload, 2 on usage errors.
*/
import { readFileSync } from "node:fs";
import { loadDedupIndex } from "../../../core/brain/dedup-hash.ts";
import {
commitExtractedSignals,
ExtractSignalsError,
} from "../../../core/brain/extract-signals.ts";
import {
EXTRACT_MINING_TOMBSTONE_SKIP_REASON,
planExtractSignalsPrefiltered,
recordExtractPrefilterCommit,
resolveExtractPrefilterConfig,
} from "../../../core/brain/extract-signals-prefilter.ts";
import { resolveTokenImpactLedgerEnabled } from "../../../core/config.ts";
import { ResponseCheckError } from "../../../core/brain/response-checks.ts";
import { ResponseShapeError } from "../../../core/brain/response-shape.ts";
import {
parsePayloadJson,
PayloadJsonError,
payloadStripNote,
type PayloadStrip,
} from "../../../core/brain/payload-json.ts";
import {
brainVerbContext,
fail,
normalizeFlagString,
ok,
okJson,
parse,
resolveBrainAgent,
usageError,
} from "../helpers.ts";
const USAGE =
"usage: o2b brain extract-signals <session-ref> [--payload <json> | --payload-file <path>] " +
"[--surveyed-turns-hash <sha256>] [--force] [--agent <name>] [--vault <path>] [--json]";
/** Refusals the operator caused, reported without a stack. */
const NAMED_REFUSALS = [ExtractSignalsError, ResponseShapeError, ResponseCheckError] as const;
function isNamedRefusal(err: unknown): err is Error {
return NAMED_REFUSALS.some((type) => err instanceof type);
}
export async function cmdBrainExtractSignals(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
agent: { type: "string" },
payload: { type: "string" },
"payload-file": { type: "string" },
"surveyed-turns-hash": { type: "string" },
force: { type: "boolean" },
json: { type: "boolean" },
});
const sessionRef = positional[0];
if (!sessionRef || sessionRef.trim() === "") return usageError(USAGE);
const asJson = flags["json"] === true;
const surveyedTurnsHashRaw = normalizeFlagString(flags["surveyed-turns-hash"]);
if (flags["surveyed-turns-hash"] !== undefined && surveyedTurnsHashRaw === null) {
return usageError(
`${USAGE}\nerror: --surveyed-turns-hash must be a non-empty string when provided`,
);
}
try {
const { config, vault } = brainVerbContext(flags);
const rawPayload =
typeof flags["payload"] === "string"
? (flags["payload"] as string)
: typeof flags["payload-file"] === "string"
? readFileSync(flags["payload-file"] as string, "utf8")
: null;
const decisionModel = resolveExtractPrefilterConfig(vault, config);
if (rawPayload === null) {
const plan = await planExtractSignalsPrefiltered(vault, sessionRef, {
now: new Date(),
decisionModel,
tokenImpactEnabled: decisionModel !== null && resolveTokenImpactLedgerEnabled(config),
// The re-mine escape: bypass the zero-yield tombstone for this one
// plan call (no payload here, so this IS the plan call).
force: flags["force"] === true,
});
if (asJson) {
okJson({
ok: true,
session_id: plan.sessionId,
generated_at: plan.generatedAt,
boundary_decision: plan.boundaryDecision,
turns_scanned: plan.turnsScanned,
turns_mined: plan.turnsMined.map((t) => ({
turn_id: t.turnId,
text: t.text,
timestamp: t.timestamp,
})),
// The hash of the material this plan offered; a commit may pass it
// back with --surveyed-turns-hash to check the session did not
// change in between.
surveyed_turns_hash: plan.surveyedTurnsHash,
cap: plan.cap,
confidence_floor: plan.confidenceFloor,
llm_step: plan.llmStep,
// Present only while the decision-model turn pre-filter is on.
...(plan.turnsDropped !== undefined ? { turns_dropped: plan.turnsDropped } : {}),
...(plan.skipped !== undefined
? {
skipped: {
reason: plan.skipped.reason,
...(plan.skipped.turnsDropped !== undefined
? { turns_dropped: plan.skipped.turnsDropped }
: {}),
...(plan.skipped.miningOutcome !== undefined
? {
mining_outcome: {
written: plan.skipped.miningOutcome.written,
staged: plan.skipped.miningOutcome.staged,
deduped: plan.skipped.miningOutcome.deduped,
durability_rejected: plan.skipped.miningOutcome.durabilityRejected,
},
}
: {}),
},
}
: {}),
...(plan.decisionModel !== undefined
? { decision_model: { degraded: plan.decisionModel.degraded } }
: {}),
// Present only when the plan could not record its survey; a
// barren commit then needs --surveyed-turns-hash to tombstone.
...(plan.surveyRecordFailure !== undefined
? { survey_record_failure: plan.surveyRecordFailure }
: {}),
});
return 0;
}
ok(`session: ${plan.sessionId} (${plan.turnsScanned} imported turn(s))`);
if (plan.skipped !== undefined) {
if (plan.skipped.reason === EXTRACT_MINING_TOMBSTONE_SKIP_REASON) {
const outcome = plan.skipped.miningOutcome!;
// The recorded breakdown is the evidence, so every field is
// rendered from the record, never asserted from a hardcoded
// zero: a hand-restored or future-written entry must read the
// same in text as the --json surface prints it.
ok(
`nothing to mine: this session was already mined at its current content and ` +
`yielded nothing (written ${outcome.written}, staged ${outcome.staged}, ` +
`deduped ${outcome.deduped}, ` +
`durability-rejected ${outcome.durabilityRejected}); ` +
`re-run with --force to re-mine it`,
);
return 0;
}
ok(
`nothing to mine: the decision-model pre-filter dropped all ` +
`${plan.skipped.turnsDropped} user turn(s)`,
);
return 0;
}
ok(`mining ${plan.turnsMined.length} user turn(s)`);
if (plan.turnsDropped !== undefined && plan.turnsDropped.length > 0) {
ok(`dropped by the decision-model pre-filter: ${plan.turnsDropped.length} turn(s)`);
}
ok(`limits: at most ${plan.cap} items, confidence >= ${plan.confidenceFloor}`);
if (plan.llmStep !== null) {
ok(`needs-llm-step: ${plan.llmStep.step} -> ${plan.llmStep.target_path}`);
ok(`surveyed turns hash: ${plan.surveyedTurnsHash}`);
if (plan.surveyRecordFailure !== undefined) {
ok(
`survey not recorded (${plan.surveyRecordFailure}); pass --surveyed-turns-hash ` +
`with the commit so a barren answer still records its tombstone`,
);
}
}
return 0;
}
let payload: unknown;
let strip: PayloadStrip | undefined;
try {
const parsed = parsePayloadJson(rawPayload);
payload = parsed.payload;
strip = parsed.strip;
} catch (error) {
// Reported here rather than by the ingress: at this point the mistake
// is the JSON the operator typed, and a path inside a payload the CLI
// never parsed would not tell them what to fix. A refusal after a
// strip attempt names the attempt (t_dac8bf7e).
if (error instanceof PayloadJsonError) {
if (!asJson) return fail(error.message);
okJson({ ok: false, message: error.message });
return 1;
}
throw error;
}
const now = new Date();
const res = commitExtractedSignals(vault, sessionRef, payload, {
agent: resolveBrainAgent(flags, config),
now,
// Loaded with parallel I/O here, where the caller can await it; the
// commit's own fallback is the synchronous walk.
dedup: await loadDedupIndex(vault),
// The answered plan's surveyed hash, when relayed: a check that the
// session did not change since the plan. Absent, the commit checks
// the survey the plan recorded instead.
...(surveyedTurnsHashRaw !== null ? { surveyedTurnsHash: surveyedTurnsHashRaw } : {}),
});
recordExtractPrefilterCommit(vault, decisionModel, res, now);
if (asJson) {
okJson({
ok: true,
session_id: res.sessionId,
written: res.written.map((w) => ({ id: w.id, path: w.path, topic: w.topic })),
staged: res.staged,
deduped: res.deduped,
durability_rejected: res.durabilityRejected,
rejected: res.rejected.map((r) => ({ topic: r.topic, reason: r.reason })),
// Present only when the commit succeeded but the zero-yield
// tombstone could not be recorded.
...(res.miningLedgerFailure !== undefined
? { mining_ledger_failure: res.miningLedgerFailure }
: {}),
// Present only when a leading <think> block was stripped (t_dac8bf7e).
...(strip !== undefined ? { note: payloadStripNote(strip) } : {}),
});
return 0;
}
ok(
`wrote ${res.written.length} signal(s)` +
(res.staged > 0 ? ` (staged for approval)` : "") +
`, deduped ${res.deduped}, durability-rejected ${res.durabilityRejected}`,
);
if (res.miningLedgerFailure !== undefined) {
ok(`mining ledger not updated: ${res.miningLedgerFailure}`);
}
if (strip !== undefined) ok(payloadStripNote(strip));
for (const r of res.rejected) ok(`rejected: ${r.topic} (${r.reason})`);
return 0;
} catch (err) {
const message = isNamedRefusal(err)
? err.message
: `extract-signals failed: ${(err as Error).message ?? String(err)}`;
if (asJson) {
okJson({ ok: false, message });
return 1;
}
return fail(message);
}
}