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 continuity export` (Memory Observability Suite,
* t_51959aeb): read-only trajectory export of the continuity store as
* ATOF JSONL or ATIF v1.7 documents. Mapping decisions live in
* docs/brainstorm/memory-observability-suite/atof-atif-mapping.md.
*
* Privacy: the exporter consumes the continuity read-model, which drops
* `private` records and never un-masks redacted text, and then hands the
* loaded records to the shared egress guard before rendering.
*
* The second pass is not redundant. The read model's upstream redaction
* runs at WRITE time with the redactor's default options, so
* `redactTokens` and `redactUrlCredentials` are both off - the two the
* export boundary turns on precisely because a false negative there is
* unrecoverable. A vendor key, a bare high-entropy token and a
* `user:pass@host` URL all left through here verbatim while every other
* export verb redacted them. Write-time coverage also says nothing about
* a record already on disk or appended by another writer: the read model
* never re-scans. Scanning what this verb actually READ answers both.
*
* The third subcommand, `promote` (issue #277), is the one that writes:
* it re-renders `host_memory_write` records as unconfirmed preference
* pages through the read-model, dry-run by default, sealed with an
* approval digest an apply must carry back.
*/
import { mkdirSync, writeFileSync } from "node:fs";
import { join, resolve } from "node:path";
import type { PlannedFile } from "../../../core/brain/claude-memory-plan.ts";
import { loadNormalizedContinuityRecords } from "../../../core/brain/continuity/read-model.ts";
import { promoteHostMemory } from "../../../core/brain/continuity/promote-host-memory.ts";
import {
PromoteConflictsError,
PromoteManifestCorruptError,
type PromoteConflictsPartialProgress,
type PromoteHostMemoryResult,
} from "../../../core/brain/continuity/promote-host-memory.ts";
import {
deriveUsageSignals,
rankByUsageDecay,
} from "../../../core/brain/continuity/usage-signal.ts";
import { renderAtofEvents } from "../../../core/brain/continuity/export-atof.ts";
import {
EGRESS_OUTCOME,
EGRESS_REDACTION_NOTICE,
redactForEgress,
} from "../../../core/egress/guard.ts";
import {
countSessionlessRecords,
renderAtifTrajectories,
} from "../../../core/brain/continuity/export-atif.ts";
import { OPEN_SECOND_BRAIN_VERSION } from "../../../core/version.ts";
import { brainVerbContext, fail, parse, usageError } from "../helpers.ts";
const CLI_VERSION: string = OPEN_SECOND_BRAIN_VERSION;
const USAGE =
"usage: o2b brain continuity export --format atof|atif [--session <id>] [--month YYYY-MM] [--out <dir>] [--json]\n" +
" o2b brain continuity rank [--kind <kind>] [--limit N] [--json]\n" +
" o2b brain continuity promote [--month YYYY-MM] [--apply] [--approval-digest <hex>] [--json]";
export async function cmdBrainContinuity(argv: string[]): Promise<number> {
const subcommand = argv[0];
if (subcommand === "export") return exportContinuity(argv.slice(1));
if (subcommand === "rank") return rankContinuity(argv.slice(1));
if (subcommand === "promote") return promoteContinuity(argv.slice(1));
return fail(USAGE);
}
function exportContinuity(argv: string[]): number {
const { flags } = parse(argv, {
vault: { type: "string" },
format: { type: "string" },
session: { type: "string" },
month: { type: "string" },
out: { type: "string" },
json: { type: "boolean" },
});
const format = typeof flags["format"] === "string" ? flags["format"].trim() : "";
if (format !== "atof" && format !== "atif") return fail(USAGE);
const month = typeof flags["month"] === "string" ? flags["month"].trim() : undefined;
if (month !== undefined && !/^\d{4}-\d{2}$/.test(month)) {
return fail("brain continuity export: --month must look like YYYY-MM");
}
const session = typeof flags["session"] === "string" ? flags["session"].trim() : undefined;
const outDir = resolve(typeof flags["out"] === "string" ? flags["out"].trim() : ".");
const vault = brainVerbContext(flags).vault;
const loaded = loadNormalizedContinuityRecords(vault, {
...(session !== undefined && session !== "" ? { sessionId: session } : {}),
...(month !== undefined ? { since: `${month}-01`, until: `${month}-31T23:59:59.999Z` } : {}),
});
// Before the directory is created: a refusal leaves no trace of a write
// that did not happen.
const verdict = redactForEgress("brain-continuity-export", loaded);
if (verdict.outcome !== EGRESS_OUTCOME.released) return fail(verdict.detail);
const records = verdict.payload;
mkdirSync(outDir, { recursive: true });
const written: string[] = [];
let skippedSessionless = 0;
if (format === "atof") {
const lines = renderAtofEvents(records);
const path = join(outDir, `o2b-continuity-${month ?? "all"}.atof.jsonl`);
writeFileSync(path, lines.length > 0 ? `${lines.join("\n")}\n` : "", "utf8");
written.push(path);
} else {
skippedSessionless = countSessionlessRecords(records);
for (const trajectory of renderAtifTrajectories(records, { agentVersion: CLI_VERSION })) {
const path = join(outDir, `o2b-continuity-${safeName(trajectory.session_id)}.atif.json`);
writeFileSync(path, `${JSON.stringify(trajectory, null, 2)}\n`, "utf8");
written.push(path);
}
}
// stderr, so stdout stays byte-identical and parseable.
if (verdict.redacted) process.stderr.write(EGRESS_REDACTION_NOTICE);
if (flags["json"] === true) {
process.stdout.write(
`${JSON.stringify(
{
format,
records: records.length,
skipped_sessionless: skippedSessionless,
files: written,
},
null,
2,
)}\n`,
);
return 0;
}
process.stdout.write(`exported ${records.length} record(s) as ${format}\n`);
for (const path of written) process.stdout.write(` ${path}\n`);
if (skippedSessionless > 0) {
process.stdout.write(` skipped ${skippedSessionless} record(s) without a session id\n`);
}
return 0;
}
const DEFAULT_RANK_KIND = "pre_compact_extract";
const DEFAULT_RANK_LIMIT = 20;
/**
* `o2b brain continuity rank`: list working-memory continuity records
* ordered by usage-driven decay weight (freshest and most-recalled
* first, stale and untouched last). Read-only; the store is never
* mutated. Default scope is the `pre_compact_extract` working-memory
* kind; `--kind <k>` narrows to another kind and `--all` ranks every
* kind.
*/
function rankContinuity(argv: string[]): number {
const { flags } = parse(argv, {
vault: { type: "string" },
kind: { type: "string" },
limit: { type: "string" },
all: { type: "boolean" },
json: { type: "boolean" },
});
const all = flags["all"] === true;
const kind = typeof flags["kind"] === "string" ? flags["kind"].trim() : DEFAULT_RANK_KIND;
let limit = DEFAULT_RANK_LIMIT;
if (typeof flags["limit"] === "string") {
const parsed = Number(flags["limit"]);
if (!Number.isInteger(parsed) || parsed < 1) {
return usageError("brain continuity rank: --limit must be a positive integer");
}
limit = parsed;
}
const vault = brainVerbContext(flags).vault;
const records = loadNormalizedContinuityRecords(vault, all ? {} : { kind });
const signals = deriveUsageSignals(vault);
const ranked = rankByUsageDecay(records, signals, Date.now()).slice(0, limit);
if (flags["json"] === true) {
process.stdout.write(
`${JSON.stringify(
{
scope: all ? "all" : kind,
total: records.length,
ranked: ranked.map((entry) => ({
id: entry.record.id,
kind: entry.record.kind,
created_at: entry.record.createdAt,
weight: entry.weight,
access_count: entry.accessCount,
last_access_at:
entry.lastAccessAtMs !== null ? new Date(entry.lastAccessAtMs).toISOString() : null,
})),
},
null,
2,
)}\n`,
);
return 0;
}
if (ranked.length === 0) {
process.stdout.write(`no ${all ? "" : `${kind} `}continuity records to rank\n`);
return 0;
}
process.stdout.write(`ranked ${ranked.length} of ${records.length} record(s) by usage decay\n`);
for (const entry of ranked) {
const lastAccess =
entry.lastAccessAtMs !== null ? new Date(entry.lastAccessAtMs).toISOString() : "never";
const preview = previewText(entry.record.payload);
process.stdout.write(
` ${entry.weight.toFixed(3)} ${entry.record.kind} uses=${entry.accessCount} last=${lastAccess}${preview}\n`,
);
}
return 0;
}
function previewText(payload: Readonly<Record<string, unknown>>): string {
const text = payload["text"];
if (typeof text !== "string" || text.length === 0) return "";
const trimmed = text.length > 80 ? `${text.slice(0, 77)}...` : text;
return ` ${trimmed.replace(/\s+/g, " ")}`;
}
function safeName(value: string): string {
return value.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120);
}
/**
* `o2b brain continuity promote`: re-render `host_memory_write` records
* as unconfirmed preference pages (issue #277). Dry-run by default - it
* plans, seals the plan and prints the digest, and writes nothing.
* `--apply` lands the plan; non-interactively it must carry the dry
* run's digest via `--approval-digest`, exactly as import-claude-memory
* does, so what lands is what was reviewed.
*/
function promoteContinuity(argv: string[]): number {
const { flags } = parse(argv, {
vault: { type: "string" },
month: { type: "string" },
apply: { type: "boolean" },
"approval-digest": { type: "string" },
json: { type: "boolean" },
});
const month = typeof flags["month"] === "string" ? flags["month"].trim() : undefined;
if (month !== undefined && !/^\d{4}-\d{2}$/.test(month)) {
return usageError("brain continuity promote: --month must look like YYYY-MM");
}
const mode = flags["apply"] === true ? "apply" : "dry-run";
const approvalDigest =
typeof flags["approval-digest"] === "string" ? flags["approval-digest"].trim() : undefined;
// A dry run COMPUTES a digest; it cannot consume one. Refuse the
// pairing by name instead of silently dropping the value.
if (mode !== "apply" && approvalDigest !== undefined) {
return usageError(
"brain continuity promote: --approval-digest applies to --apply; " +
"a dry run computes a digest, it does not consume one",
);
}
if (mode === "apply" && approvalDigest === undefined && !process.stdin.isTTY) {
return usageError(
"brain continuity promote: --apply requires --approval-digest in non-interactive " +
"mode (run the default dry run first, then apply with the digest it prints)",
);
}
const vault = brainVerbContext(flags).vault;
const asJson = flags["json"] === true;
try {
const res = promoteHostMemory({
vault,
mode,
...(month !== undefined ? { month } : {}),
...(approvalDigest !== undefined ? { approvalDigest } : {}),
});
if (asJson) process.stdout.write(`${renderPromoteJson(month, res)}\n`);
else if (mode === "dry-run") printPromotePlan(res);
else {
printPromoteApply(
res.applied,
res.skipped,
res.skippedUnchanged,
res.snapshotRunId,
res.redactedCount,
res.privateCount,
res.total,
res.conflicts,
);
}
if (res.manifestCorrupt) printManifestCorruptWarning();
return 0;
} catch (err) {
if (err instanceof PromoteConflictsError) {
// The safe writes already landed; report the applied progress, then
// the conflicts, and exit 2.
const partial = err.partial;
if (asJson && partial !== null) {
process.stdout.write(`${renderPromotePartialJson(month, partial, err.conflicts)}\n`);
} else {
if (partial !== null) {
printPromoteApply(
partial.applied,
partial.skipped,
partial.skippedUnchanged,
partial.snapshotRunId,
partial.redactedCount,
partial.privateCount,
partial.total,
err.conflicts,
);
}
process.stderr.write("conflicts:\n");
for (const c of err.conflicts) {
process.stderr.write(
` ${c.prefId} already exists in Brain but is not in ` +
`Brain/.imports/host-memory-promotions.json (${c.basename})\n`,
);
}
}
return 2;
}
if (err instanceof PromoteManifestCorruptError) {
return fail(`brain continuity promote: ${(err as Error).message}`);
}
return fail(`brain continuity promote: ${(err as Error).message}`);
}
}
function renderPromoteJson(month: string | undefined, res: PromoteHostMemoryResult): string {
return renderPromoteEnvelope({
mode: res.mode,
month,
total: res.total,
plans: res.plans,
applied: res.applied,
skipped: res.skipped,
skippedUnchanged: res.skippedUnchanged,
conflicts: res.conflicts,
redactedCount: res.redactedCount,
privateCount: res.privateCount,
manifestCorrupt: res.manifestCorrupt,
digest: res.digest,
snapshotRunId: res.snapshotRunId,
});
}
/**
* The one JSON envelope every promote exit spells: the same key set on
* the dry run, the clean apply and the conflict path, with `conflicts`
* always present (empty when none) and `plans` carrying the full plan
* even when the run stopped at exit 2 - a consumer keying on `plans`
* must not read zero rows off a partial run, and one keying on
* `conflicts` must not meet the key only on that path.
*/
function renderPromoteEnvelope(parts: {
mode: string;
month: string | undefined;
total: number;
plans: ReadonlyArray<PlannedFile>;
applied: ReadonlyArray<PlannedFile>;
skipped: ReadonlyArray<{ id: string; reason: string }>;
skippedUnchanged: ReadonlyArray<PlannedFile>;
conflicts: ReadonlyArray<PlannedFile>;
redactedCount: number;
privateCount: number;
manifestCorrupt: boolean;
digest: string;
snapshotRunId: string | null;
}): string {
return JSON.stringify(
{
mode: parts.mode,
month: parts.month ?? null,
total: parts.total,
counts: {
plans: parts.plans.length,
applied: parts.applied.length,
skipped: parts.skipped.length,
skipped_unchanged: parts.skippedUnchanged.length,
conflicts: parts.conflicts.length,
private_dropped: parts.privateCount,
redacted: parts.redactedCount,
},
manifest_corrupt: parts.manifestCorrupt,
digest: parts.digest,
snapshot: parts.snapshotRunId,
plans: parts.plans.map((p) => ({ id: p.basename, pref_id: p.prefId, action: p.action })),
skipped: parts.skipped.map((s) => ({ id: s.id, reason: s.reason })),
applied: parts.applied.map((p) => ({ id: p.basename, pref_id: p.prefId, action: p.action })),
conflicts: parts.conflicts.map((p) => ({
id: p.basename,
pref_id: p.prefId,
action: p.action,
})),
},
null,
2,
);
}
function renderPromotePartialJson(
month: string | undefined,
partial: PromoteConflictsPartialProgress,
conflicts: PromoteConflictsError["conflicts"],
): string {
return renderPromoteEnvelope({
mode: "apply",
month,
total: partial.total,
plans: partial.plans,
applied: partial.applied,
skipped: partial.skipped,
skippedUnchanged: partial.skippedUnchanged,
conflicts,
redactedCount: partial.redactedCount,
privateCount: partial.privateCount,
manifestCorrupt: partial.manifestCorrupt,
digest: partial.digest,
snapshotRunId: partial.snapshotRunId,
});
}
function printManifestCorruptWarning(): void {
process.stderr.write(
"warning: Brain/.imports/host-memory-promotions.json could not be read as the " +
"manifest shape - this plan was computed against an empty history and --apply " +
"refuses until the file is reconciled\n",
);
}
function printPromotePlan(res: PromoteHostMemoryResult): void {
process.stdout.write(
`promote plan: ${res.plans.length} actionable, ${res.skipped.length} skipped\n`,
);
if (res.privateCount > 0 || res.redactedCount > 0) {
process.stdout.write(
` saw ${res.total} record(s): ${res.privateCount} private dropped, ` +
`${res.redactedCount} redacted (masked text promoted)\n`,
);
}
process.stdout.write(`approval-digest: ${res.digest}\n`);
for (const p of res.plans) process.stdout.write(` ${p.action} ${p.prefId} (${p.basename})\n`);
for (const s of res.skipped) process.stdout.write(` SKIP ${s.id}: ${s.reason}\n`);
}
function printPromoteApply(
applied: ReadonlyArray<{ prefId: string }>,
skipped: ReadonlyArray<{ id: string; reason: string }>,
skippedUnchanged: ReadonlyArray<unknown>,
snapshotRunId: string | null,
redactedCount: number,
privateCount: number,
total: number,
conflicts: ReadonlyArray<unknown>,
): void {
process.stdout.write(
`applied: ${applied.length}; unchanged: ${skippedUnchanged.length}; skipped: ${skipped.length}\n`,
);
if (privateCount > 0 || redactedCount > 0) {
process.stdout.write(
` saw ${total} record(s): ${privateCount} private dropped, ` +
`${redactedCount} redacted (masked text promoted)\n`,
);
}
if (snapshotRunId) process.stdout.write(`snapshot: ${snapshotRunId}\n`);
for (const s of skipped) process.stdout.write(` SKIP ${s.id}: ${s.reason}\n`);
if (conflicts.length > 0) process.stdout.write(`conflicts: ${conflicts.length}\n`);
}