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 hallways mine|show|promote|dismiss` (recall-quality wave,
* Lane B / t_13a82a31): the CLI over the session-mined ledger.
*
* mine - derive incidence and pairwise PMI over the mined-mention
* ledger and persist the derived artifact plus the
* reviewable proposals file; records one hallways_mine
* metric. Writes NO entity page.
* show - read the proposals artifact back (fail-soft).
* promote - the ONE bridge into the entity registry. Offered only for
* keys seen in >= N distinct sessions (default
* DEFAULT_PROMOTION_MIN_SESSIONS, override with
* --min-sessions) and never for a dismissed key; the write
* itself flows through `upsertEntity` and `relateEntities`
* exclusively, so a promoted label failing the tightened
* admission gate is refused by that gate, not by this verb.
* dismiss - silence a key across future runs.
*
* Exit codes: 0 on success/fail-soft skip, 1 on an operational failure
* or a refused promotion, 2 on usage errors.
*/
import { existsSync } from "node:fs";
import { join } from "node:path";
import {
computeHallways,
DEFAULT_PROMOTION_MIN_SESSIONS,
dismissHallwayKey,
HALLWAYS_PROPOSALS_REL,
hallwaysKeyId,
readDismissedHallwayKeys,
writeHallwaysArtifact,
writeHallwaysProposals,
} from "../../../core/brain/link-graph/hallways.ts";
import { SESSION_MINING_FAMILIES } from "../../../core/brain/link-graph/session-mining.ts";
import { getEntity, relateEntities, upsertEntity } from "../../../core/brain/entities/registry.ts";
import { appendMetric } from "../../../core/brain/metrics.ts";
import {
createSafeguard,
OPERATION,
resolveSafeguardTimeoutMs,
} from "../../../core/brain/safeguard.ts";
import { InvalidEntityLabelError } from "../../../core/brain/entities/canonical.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import { parseFrontmatter } from "../../../core/vault.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import { emitNextStep, type AdvisoryStream } from "../../advisory-rail.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { brainVerbContext, fail, ok, okJson, parse, resolveBrainAgent } from "../helpers.ts";
const USAGE =
"usage: o2b brain hallways mine [--min-co N] [--min-score X] [--limit N] [--min-sessions N] [--progress] | " +
"show | promote <family> <key> [--min-sessions N] | dismiss <family> <key> [--vault <path>] [--json]";
export async function cmdBrainHallways(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
"min-co": { type: "string" },
"min-score": { type: "string" },
limit: { type: "string" },
"min-sessions": { type: "string" },
progress: { type: "boolean" },
json: { type: "boolean" },
});
const asJson = flags["json"] === true;
const action = positional[0];
if (
action === undefined ||
!["mine", "show", "promote", "dismiss"].includes(action) ||
((action === "promote" || action === "dismiss") && positional.length !== 3) ||
((action === "mine" || action === "show") && positional.length !== 1)
) {
process.stderr.write(`${USAGE}\n`);
return 2;
}
const { config, vault } = brainVerbContext(flags);
// The advisory stream, for the one forward pointer this verb can emit
// (the absent-artifact case below): the rail owns what reaches stdout.
const stream: AdvisoryStream = { command: "brain", argv: ["hallways"], jsonRequested: asJson };
// `promote` names a mined family: the ledger is family-scoped, so a
// family that never mines is a typo, not a refusal.
if (action === "promote" || action === "dismiss") {
const family = positional[1]!;
if (!(SESSION_MINING_FAMILIES as readonly string[]).includes(family)) {
process.stderr.write(
`${USAGE}\nerror: unknown mining family '${family}' - the mined families are ${SESSION_MINING_FAMILIES.join(", ")}\n`,
);
return 2;
}
}
const minSessions = parsePositiveInt(flags["min-sessions"] as string | undefined);
if (minSessions === false) {
process.stderr.write("brain hallways: --min-sessions must be a positive integer\n");
return 2;
}
if (action === "dismiss") {
const added = dismissHallwayKey(vault, positional[1]!, positional[2]!);
if (asJson) {
okJson({ dismissed: hallwaysKeyId(positional[1]!, positional[2]!), added });
} else ok(added ? "key dismissed" : "key was already dismissed");
return 0;
}
if (action === "show") {
const path = join(vault, HALLWAYS_PROPOSALS_REL);
if (!existsSync(path)) {
if (asJson) {
okJson({ exists: false, proposals: 0, ...nextCommandField("hallways-proposals-absent") });
} else ok("no proposals artifact yet");
// Fail-soft, but not silent about the fix: the pointer rides the
// advisory rail like every other one.
emitNextStep("hallways-proposals-absent", stream);
return 0;
}
const [meta, body] = parseFrontmatter(path);
if (asJson) {
okJson({
exists: true,
path: "Brain/proposals/hallways.md",
generated_at: meta["generated_at"] ?? null,
proposals: Number(meta["proposals"] ?? 0),
keys: Number(meta["keys"] ?? 0),
pairs: Number(meta["pairs"] ?? 0),
});
} else ok(body);
return 0;
}
if (action === "promote") {
return promote(vault, {
family: positional[1]!,
key: positional[2]!,
minSessions: minSessions ?? DEFAULT_PROMOTION_MIN_SESSIONS,
agent: resolveBrainAgent(flags, config ?? ""),
config,
asJson,
});
}
// mine
const minCo = parsePositiveInt(flags["min-co"] as string | undefined);
const limit = parsePositiveInt(flags["limit"] as string | undefined);
const minScoreRaw = flags["min-score"] as string | undefined;
const minScore = minScoreRaw === undefined ? undefined : Number(minScoreRaw);
if (
minCo === false ||
limit === false ||
(minScoreRaw !== undefined && !Number.isFinite(minScore))
) {
process.stderr.write(
"brain hallways mine: --min-co and --limit must be positive integers, --min-score a number\n",
);
return 2;
}
const now = new Date();
// Progress is opt-in, exactly like `brain bridges discover`: attaching a
// sink by default would change the stderr of every existing invocation.
const observation =
flags["progress"] === true
? attachProgress({ command: "brain", argv: ["hallways"], jsonRequested: asJson })
: null;
reportProgressRefusal(observation);
try {
const dismissed = readDismissedHallwayKeys(vault);
const result = computeHallways(vault, {
...(minCo !== undefined ? { minCoSessions: minCo } : {}),
...(minScore !== undefined ? { minScore } : {}),
...(limit !== undefined ? { limit } : {}),
dismissed,
safeguard: createSafeguard({
operation: OPERATION.sessions,
timeoutMs: resolveSafeguardTimeoutMs(OPERATION.sessions, config ?? undefined),
}),
...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
});
writeHallwaysArtifact(vault, result, { generatedAt: isoSecond(now) });
writeHallwaysProposals(vault, result, {
now,
dismissed,
...(minSessions !== undefined ? { minSessions } : {}),
});
try {
appendMetric(vault, {
surface: "hallways_mine",
runAt: isoSecond(now),
payload: {
session_count: result.sessionCount,
keys: result.keys.length,
pairs: result.pairs.length,
mention_rows: result.mentionRows,
skipped_rows: result.skippedRows,
dismissed_total: dismissed.size,
promotion_min_sessions: minSessions ?? DEFAULT_PROMOTION_MIN_SESSIONS,
},
});
} catch {
// Metrics are observability, not correctness.
}
if (asJson) {
okJson({
artifact: "Brain/link-graph/hallways.json",
proposals: "Brain/proposals/hallways.md",
session_count: result.sessionCount,
mention_rows: result.mentionRows,
skipped_rows: result.skippedRows,
keys: result.keys.length,
pairs: result.pairs.length,
promotion_min_sessions: minSessions ?? DEFAULT_PROMOTION_MIN_SESSIONS,
});
} else {
ok(
`mined ${result.keys.length} keys over ${result.sessionCount} sessions; ` +
`${result.pairs.length} pairs; proposals at Brain/proposals/hallways.md`,
);
}
return 0;
} catch (exc) {
return fail(`brain hallways mine failed: ${(exc as Error).message}`);
}
}
/**
* Promote one mined key. The gate first (threshold, dismissals), then
* the registry: `upsertEntity` for the page, `relateEntities` for every
* association whose other half is already promoted. No other write path
* exists here - which is exactly why a label the tightened admission
* gate refuses cannot become an entity page through this verb.
*/
function promote(
vault: string,
args: {
readonly family: string;
readonly key: string;
readonly minSessions: number;
readonly agent: string;
/** Config path the safeguard ladder resolves promote's deadline from. */
readonly config: string | null;
readonly asJson: boolean;
},
): number {
const dismissed = readDismissedHallwayKeys(vault);
if (dismissed.has(hallwaysKeyId(args.family, args.key))) {
return refuse(
args.asJson,
`promote refused: '${args.key}' (${args.family}) is dismissed - a dismissal is final ` +
"for this artifact (re-mining keeps the key silenced), so there is no undo verb: " +
"the way back is removing its id from Brain/proposals/hallways-dismissed.json by hand",
);
}
// The threshold is read off the CURRENT ledger fold, never the stored
// artifact: the artifact is a cache, the gate is a decision. The fold is
// the same O(k^2) pass `mine` runs, so it carries mine's bounded-wait
// deadline too - a promote over a huge ledger stops at a checkpoint and
// reports the timeout instead of owning the thread.
let derivation: ReturnType<typeof computeHallways>;
try {
derivation = computeHallways(vault, {
dismissed,
safeguard: createSafeguard({
operation: OPERATION.sessions,
timeoutMs: resolveSafeguardTimeoutMs(OPERATION.sessions, args.config ?? undefined),
}),
});
} catch (exc) {
return fail(`brain hallways promote failed: ${(exc as Error).message}`);
}
const stat = derivation.keys.find((k) => k.family === args.family && k.key === args.key);
if (stat === undefined || stat.sessionCount < args.minSessions) {
return refuse(
args.asJson,
`promote refused: '${args.key}' (${args.family}) is seen in ${stat?.sessionCount ?? 0} ` +
`distinct sessions, below the promotion threshold of ${args.minSessions} ` +
"(raise coverage or lower --min-sessions)",
);
}
try {
const out = upsertEntity(vault, {
category: args.family,
name: args.key,
agent: args.agent,
now: new Date(),
bodyOnCreate:
"Promoted from the session-mining ledger: this key kept turning up in " +
"imported session transcripts. Provenance-grade until an operator curates it.",
});
// Associations whose other half is already an entity get a real
// relation edge; the rest can be promoted later, and a later promote
// relates back. `relateEntities` resolves and refuses on its own, so
// a partner that is not (yet) an entity simply contributes nothing.
const related: string[] = [];
for (const pair of derivation.pairs) {
const other =
pair.left === hallwaysKeyId(args.family, args.key)
? splitKeyId(pair.right)
: pair.right === hallwaysKeyId(args.family, args.key)
? splitKeyId(pair.left)
: null;
if (other === null) continue;
const partner = getEntity(vault, { category: other.family, query: other.key });
if (partner === null) continue;
relateEntities(vault, {
from: { category: args.family, query: args.key },
relation: "related",
to: { category: other.family, query: other.key },
now: new Date(),
});
related.push(partner.id);
}
if (args.asJson) {
okJson({
promoted: true,
created: out.created,
entity: out.entity.id,
sessions: stat.sessionCount,
related,
});
} else {
ok(
`${out.created ? "created" : "updated"}: ${out.entity.id} ` +
`(${stat.sessionCount} sessions${related.length > 0 ? `; related to ${related.join(", ")}` : ""})`,
);
}
return 0;
} catch (exc) {
if (exc instanceof InvalidEntityLabelError) {
// The pinned coupling: the admission path refused, so this verb
// reports the gate's verdict and writes nothing.
return refuse(
args.asJson,
`promote refused: the entity admission gate rejected '${args.key}' ` +
`(${exc.reason}) - a mined key is a suggestion, the registry is the decision`,
);
}
return fail(`brain hallways promote failed: ${(exc as Error).message}`);
}
}
/** Refusal shape: message on stderr (or JSON), exit 1, nothing written. */
function refuse(asJson: boolean, message: string): number {
if (asJson) {
process.stdout.write(
`${JSON.stringify({ ok: false, refused: true, reason: message }, null, 2)}\n`,
);
} else {
process.stderr.write(`error: ${message}\n`);
}
return 1;
}
function splitKeyId(id: string): { family: string; key: string } {
const sep = id.indexOf(":");
return { family: id.slice(0, sep), key: id.slice(sep + 1) };
}
function parsePositiveInt(raw: string | undefined): number | undefined | false {
if (raw === undefined) return undefined;
const n = Number(raw);
return Number.isInteger(n) && n > 0 ? n : false;
}