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
/**
* `mergePreferences` — explicit operator-initiated merge of two
* confirmed/quarantine preferences (§12).
*
* Contract: `keep` retains identity. `drop` retires under
* `BRAIN_RETIRED_REASON.mergedInto` with a `superseded_by` pointing
* at `keep`. `keep` picks up the sorted-dedup union of
* `evidenced_by`, the sum of `applied_count` / `violated_count`, and
* `max(last_evidence_at)`. `confidence` and `confidence_value` are
* NOT recomputed here — the next `dream` pass owns that derivation;
* recomputing in-place would split the source of truth.
*
* All guards (`same-id`, `keep-not-found`, `drop-not-found`,
* `topic-mismatch`, `scope-mismatch`, `pin-parity`) are data
* invariants and throw `BrainMergeError`. `--force` at the CLI
* level does NOT bypass them — it only skips the interactive
* confirmation prompt.
*
* No snapshot is created. Merge is point-precise (one keep, one
* drop). Roll-back: copy `Brain/retired/ret-<drop>.md` back to
* `Brain/preferences/pref-<drop>.md`, rerun `o2b brain dream` to
* recompute counters.
*/
import { join } from "node:path";
import { PREFERENCE_EVIDENCE_KIND, type EvidenceResult } from "../store/constants.ts";
import {
isPrivatePageFile,
isPrivatePreference,
MERGED_FROM_FIELD,
preferenceEvidenceRecord,
} from "../store/dual-write-records.ts";
import { storeWrite } from "../store/store-write.ts";
import { regenerateActiveQuiet } from "./active.ts";
import { preferencesStoreOnly, storePreferenceEntry } from "./preference-store.ts";
import { countersForShared } from "../store/read/store-entities.ts";
import { computeContentHash } from "./content-hash.ts";
import { buildEntityIndex } from "./entities/index-builder.ts";
import { guardEntityMerge, type GuardEntityLike } from "./truth/merge-guard.ts";
import { resolveAppendShardId } from "./ledger-shards.ts";
import { appendLogEvent, logShardWikilink } from "./log.ts";
import { brainDirs, preferencePath } from "./paths.ts";
import { appendPrefAudit } from "./pref-audit.ts";
import {
loadPreference,
moveToRetired,
parsePreference,
preferencePresence,
writePreference,
} from "./preference.ts";
import { isoDate, isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_RETIRED_REASON, PREF_AUDIT_OP } from "./types.ts";
import { renderPrefLink } from "./wikilink.ts";
export type BrainMergeErrorCode =
| "same-id"
| "keep-not-found"
| "drop-not-found"
| "drop-already-retired"
| "topic-mismatch"
| "scope-mismatch"
| "pin-parity"
| "unsupported-status"
| "entity-guard";
export class BrainMergeError extends Error {
readonly code: BrainMergeErrorCode;
constructor(code: BrainMergeErrorCode, message: string) {
super(message);
this.name = "BrainMergeError";
this.code = code;
}
}
export interface MergeOptions {
/** Wall clock for the run. Defaults to `new Date()`. */
readonly now?: Date;
/** Agent identity stamped into the log event. */
readonly agentName?: string;
/** When true, return the plan but make no writes. */
readonly dryRun?: boolean;
/**
* Skip the name-aware entity merge guard (t_e9692750). The CLI maps
* `--force` here; the guard otherwise refuses to collapse claims
* about different people/orgs into one preference.
*/
readonly bypassEntityGuard?: boolean;
}
export interface MergePlan {
readonly keep_id: string;
readonly drop_id: string;
readonly topic: string;
readonly scope: string | null;
readonly merged_evidenced_by: ReadonlyArray<string>;
readonly applied_sum: number;
readonly violated_sum: number;
readonly last_evidence_at: string | null;
readonly retired_path: string;
}
export function mergePreferences(
vault: string,
keepId: string,
dropId: string,
opts: MergeOptions = {},
): MergePlan {
if (keepId === dropId) {
throw new BrainMergeError("same-id", `keep and drop refer to the same preference '${keepId}'`);
}
const now = opts.now ?? new Date();
const dryRun = opts.dryRun === true;
const keepSlug = stripPrefPrefix(keepId);
const dropSlug = stripPrefPrefix(dropId);
const keepPath = preferencePath(vault, keepSlug);
const dropPath = preferencePath(vault, dropSlug);
// The pages on an unswitched machine, the store's fold once switched.
const keepPresence = preferencePresence(vault, keepSlug);
if (keepPresence !== "active") {
if (keepPresence === "retired") {
throw new BrainMergeError(
"keep-not-found",
`keep '${keepId}' is already retired; cannot merge into a retired pref`,
);
}
throw new BrainMergeError("keep-not-found", `keep preference '${keepId}' not found`);
}
const dropPresence = preferencePresence(vault, dropSlug);
if (dropPresence !== "active") {
if (dropPresence === "retired") {
throw new BrainMergeError("drop-already-retired", `drop '${dropId}' is already retired`);
}
throw new BrainMergeError("drop-not-found", `drop preference '${dropId}' not found`);
}
// Once switched the fold is the only source: a preference gone since
// the presence check is not found, and no page path is read.
const storeOnly = preferencesStoreOnly(vault);
const load = (slug: string, path: string, code: "keep-not-found" | "drop-not-found") => {
const loaded = loadPreference(vault, slug);
if (loaded !== null) return loaded;
if (storeOnly) throw new BrainMergeError(code, `preference 'pref-${slug}' not found`);
return parsePreference(path);
};
const keep = load(keepSlug, keepPath, "keep-not-found");
const drop = load(dropSlug, dropPath, "drop-not-found");
if (!isMergeableStatus(keep.status)) {
throw new BrainMergeError(
"unsupported-status",
`keep '${keepId}' has status '${keep.status}'; merge only supports confirmed or quarantine preferences`,
);
}
if (!isMergeableStatus(drop.status)) {
throw new BrainMergeError(
"unsupported-status",
`drop '${dropId}' has status '${drop.status}'; merge only supports confirmed or quarantine preferences`,
);
}
if (keep.topic !== drop.topic) {
throw new BrainMergeError(
"topic-mismatch",
`topic mismatch: keep='${keep.topic}', drop='${drop.topic}'.` +
" Merge is for near-duplicate rules in the same bucket;" +
" use `o2b brain reject` if drop is wrong rather than redundant.",
);
}
const keepScope = keep.scope ?? null;
const dropScope = drop.scope ?? null;
if (keepScope !== dropScope) {
throw new BrainMergeError(
"scope-mismatch",
`scope mismatch: keep='${keepScope ?? "(none)"}', drop='${dropScope ?? "(none)"}'.` +
" Use `o2b brain reject` instead.",
);
}
if (keep.pinned !== drop.pinned && drop.pinned) {
throw new BrainMergeError(
"pin-parity",
`drop '${dropId}' is pinned but keep '${keepId}' is not;` +
" put the pinned pref first as <keep> if you want to merge.",
);
}
// Name-aware entity guard (t_e9692750): same-topic near-duplicates
// naming different people/orgs must not collapse into one rule.
if (opts.bypassEntityGuard !== true) {
let entities: ReadonlyArray<GuardEntityLike> = [];
try {
entities = buildEntityIndex(vault).entities;
} catch {
// No readable registry means nothing to anchor against.
}
const verdict = guardEntityMerge({
keepText: `${keep.topic} ${keep.principle}`,
dropText: `${drop.topic} ${drop.principle}`,
entities,
});
if (!verdict.allowed) {
throw new BrainMergeError("entity-guard", `${verdict.reason}; pass --force to override`);
}
}
const merged_evidenced_by = mergeEvidencedBy(keep.evidenced_by, drop.evidenced_by);
// Once switched, a shared preference's private uses stay out of the
// sums the merge log event and audit trail carry (task 3.18), and a drop
// record an earlier, interrupted run of this merge already copied to the
// keep is counted once, in the keep's counters.
const counts = (pref: typeof keep, slug: string) => {
const entry = storeOnly ? storePreferenceEntry(slug) : undefined;
if (entry === undefined) return { applied: pref.applied_count, violated: pref.violated_count };
const counters = countersForShared(entry);
return { applied: counters.applied_count, violated: counters.violated_count };
};
const keepCounts = counts(keep, keepSlug);
const dropCounts = ((): { applied: number; violated: number } => {
const dropEntry = storeOnly ? storePreferenceEntry(dropSlug) : undefined;
if (dropEntry === undefined) return counts(drop, dropSlug);
const copied = new Set(
(storePreferenceEntry(keepSlug)?.state.history ?? [])
.map((record) => record.body[MERGED_FROM_FIELD])
.filter((id): id is string => typeof id === "string"),
);
let applied = 0;
let violated = 0;
for (const record of dropEntry.state.history) {
if (record.kind !== PREFERENCE_EVIDENCE_KIND || copied.has(record.id)) continue;
// A private use counts unless the keep it lands on is shared: copied
// to a private keep (or from a private drop) it is part of the keep.
const keepPrivate = storePreferenceEntry(keepSlug)?.private ?? true;
if (!dropEntry.private && !keepPrivate && dropEntry.privateRecordIds.has(record.id)) {
continue;
}
if (record.body["result"] === "applied") applied += 1;
else if (record.body["result"] === "violated") violated += 1;
}
return { applied, violated };
})();
const applied_sum = keepCounts.applied + dropCounts.applied;
const violated_sum = keepCounts.violated + dropCounts.violated;
const last_evidence_at = maxIso(keep.last_evidence_at, drop.last_evidence_at);
const plan: MergePlan = Object.freeze({
keep_id: keepId,
drop_id: dropId,
topic: keep.topic,
scope: keepScope,
merged_evidenced_by,
applied_sum,
violated_sum,
last_evidence_at,
// Once switched no page is written: the retired record's id names it.
retired_path: storeOnly
? `ret-${dropSlug}`
: join(brainDirs(vault).retired, `ret-${dropSlug}.md`),
});
if (dryRun) return plan;
// 1. Rewrite keep with the merged fields. Confidence band/value
// are NOT recomputed here — dream owns that derivation. We
// pass the existing values through so the file is consistent.
writePreference(
vault,
{
slug: keepSlug,
topic: keep.topic,
principle: keep.principle,
created_at: keep.created_at,
unconfirmed_until: keep.unconfirmed_until,
status: keep.status,
evidenced_by: merged_evidenced_by,
confirmed_at: keep.confirmed_at,
applied_count: applied_sum,
violated_count: violated_sum,
last_evidence_at,
confidence: keep.confidence,
confidence_value: keep.confidence_value,
pinned: keep.pinned,
...(keep.scope ? { scope: keep.scope } : {}),
// Rewrites the persisted keep record: a legacy scope must not
// block the merge (see `lenientScopeTags`).
lenientScopeTags: true,
...(keep.supersedes ? { supersedes: keep.supersedes } : {}),
...(keep.aliases ? { aliases: keep.aliases } : {}),
},
{ overwrite: true },
);
// 1b. Once switched the fold derives the counters from evidence records
// and ignores a counter written as a field, so the keep absorbs the
// drop's counters as evidence: one evidence record per drop
// evidence record, private when either side is.
if (storeOnly) {
const dropEntry = storePreferenceEntry(dropSlug);
const keepEntry = storePreferenceEntry(keepSlug);
// The merge's steps are separate store writes. A merge retried after
// a step past this one failed (the drop still active) must not copy
// the drop's evidence a second time: each copy names the record it
// copies, and a record the keep already holds a copy of is skipped.
const copied = new Set(
(keepEntry?.state.history ?? [])
.map((record) => record.body[MERGED_FROM_FIELD])
.filter((id): id is string => typeof id === "string"),
);
const evidence = (dropEntry?.state.history ?? []).filter(
(record) => record.kind === PREFERENCE_EVIDENCE_KIND && !copied.has(record.id),
);
if (evidence.length > 0) {
const pairPrivate = (keepEntry?.private ?? true) || (dropEntry?.private ?? true);
// A record of the drop that sits in `private` (its artifact named a
// private page) stays there as a copy too. One store write lands in
// one partition, so the shared and the private copies are two writes.
const isPrivate = (record: (typeof evidence)[number]): boolean =>
pairPrivate || (dropEntry?.privateRecordIds.has(record.id) ?? true);
for (const group of [evidence.filter((r) => !isPrivate(r)), evidence.filter(isPrivate)]) {
if (group.length === 0) continue;
storeWrite(
() =>
group.map((record) =>
preferenceEvidenceRecord({
id: keep.id,
result: record.body["result"] as EvidenceResult,
artifact:
typeof record.body["artifact"] === "string" ? record.body["artifact"] : "",
agent: opts.agentName ?? "merge",
private: isPrivate(record),
mergedFrom: record.id,
}),
),
{ vault },
);
}
}
}
// 2. Move drop to retired/ with merged-into reason. moveToRetired
// re-reads the source file, so the latest on-disk state is
// what lands in the snapshot — including drop's own counters,
// which we want preserved as audit trail.
const supersededBy = renderPrefLink({
id: keep.id,
principle: keep.principle,
});
// The retired_by link names the log shard the `merge` event below is
// about to land in, so the retirement's provenance always resolves.
// Resolved once here and handed to both writes: two independent
// resolutions are two chances to disagree about the shard.
const shardId = resolveAppendShardId();
moveToRetired(vault, dropPath, BRAIN_RETIRED_REASON.mergedInto, {
now,
retired_by: logShardWikilink(isoDate(now), shardId),
superseded_by: supersededBy,
audit: { agent: opts.agentName ?? "merge" },
});
// Per-preference mutation audit (Brain lifecycle suite F1). The keep
// pref absorbed evidence + counters; record a `merge` op on its trail.
// A merge is a lifecycle event, so it records even though keep's
// principle/scope fingerprint is unchanged. The drop's retire(merged-
// into) record is written by moveToRetired above.
{
const keepHash = computeContentHash(keep.principle, keep.scope);
appendPrefAudit(
vault,
{
pref_id: keep.id,
op: PREF_AUDIT_OP.merge,
agent: opts.agentName ?? "merge",
reason: `merged-in ${drop.id}`,
revision_before: keep.revision ?? null,
revision_after: keep.revision ?? null,
hash_before: keepHash,
hash_after: keepHash,
// The row names the drop too (`merged-in <drop>`): private when
// either side is. The drop is already in `retired/` by now.
private: () =>
(storeOnly
? (storePreferenceEntry(keepSlug)?.private ?? true)
: isPrivatePageFile(keepPath)) || isPrivatePreference(vault, dropSlug),
},
{ now },
);
}
// 3. Append a `merge` log event with audit-grade payload. The same
// shard id the retired_by link above names, so the event is where
// the link says it is.
appendLogEvent(
vault,
{
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.merge,
body: {
keep: renderPrefLink({ id: keep.id, principle: keep.principle }),
drop: renderPrefLink({ id: drop.id, principle: drop.principle }),
signal_union: `${merged_evidenced_by.length} (was ${keep.evidenced_by.length}, ${drop.evidenced_by.length})`,
applied_sum: `${applied_sum} (was ${keepCounts.applied}, ${dropCounts.applied})`,
violated_sum: `${violated_sum} (was ${keepCounts.violated}, ${dropCounts.violated})`,
agent: opts.agentName ?? "unknown",
},
},
{ deviceId: shardId },
);
// 4. Regenerate active.md so the operator sees the new state on
// their next session start.
// The digest is a page of the legacy tree; a store-only machine renders
// it on demand (design D14 item 7).
if (!preferencesStoreOnly(vault)) regenerateActiveQuiet(vault, { now });
return plan;
}
function stripPrefPrefix(id: string): string {
if (!id.startsWith("pref-") || id.length <= "pref-".length) {
throw new BrainMergeError("keep-not-found", `expected a 'pref-…' id; got '${id}'`);
}
return id.slice("pref-".length);
}
function mergeEvidencedBy(
a: ReadonlyArray<string>,
b: ReadonlyArray<string>,
): ReadonlyArray<string> {
const seen = new Set<string>();
const out: string[] = [];
for (const v of [...a, ...b]) {
if (seen.has(v)) continue;
seen.add(v);
out.push(v);
}
out.sort();
return Object.freeze(out);
}
function maxIso(a: string | null, b: string | null): string | null {
if (a === null) return b;
if (b === null) return a;
return a >= b ? a : b;
}
function isMergeableStatus(status: string): boolean {
return status === "confirmed" || status === "quarantine";
}