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
import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
import { basename, dirname, join } from "node:path";
import { existingPreferencePageText, writePreferencePageText } from "./preference-page-write.ts";
import { preferencesStoreOnly } from "./preference-store.ts";
import { digestVerifies, sealWithDigest, sha256Hex } from "../integrity/digest.ts";
import { appendLogEvent } from "./log.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_SNAPSHOT_REASON } from "./types.ts";
import { takeSnapshot } from "./snapshot-gate.ts";
import { isoSecond } from "./time.ts";
import { loadBrainConfig } from "./policy.ts";
import { DEFAULT_BRAIN_CONFIG } from "./policy/defaults.ts";
import { resolveAgentName } from "../config.ts";
import { loadManifest, saveManifest } from "./claude-memory-manifest.ts";
import { planAction, type PlannedFile } from "./claude-memory-plan.ts";
import { assertSafeMemoryPath, homeRelativePath } from "./claude-memory-paths.ts";
import { claudeMemoryBackend } from "./agent-backend/claude.ts";
import type { MemorySourceBackend } from "./agent-backend/types.ts";
import { BRAIN_PREFERENCES_REL, preferencePath } from "./paths.ts";
import { preferencePresence, resolvedOwnerFor } from "./preference.ts";
import { TagSyntaxError } from "./tag-syntax.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
export interface ImportClaudeMemoryOpts {
readonly vault: string;
readonly memoryDir: string;
readonly mode: "dry-run" | "apply";
readonly allowArbitraryMemoryPath?: boolean;
readonly now?: Date;
/**
* The plan digest a dry run computed and an operator approved (the CLI
* plumbing is `--approval-digest`). Absent, apply behaves exactly as
* it did before approval digests existed - the interactive path's
* escape hatch. Present, it is checked against the freshly computed
* plan BEFORE the snapshot or any write, and a mismatch is an
* {@link ApprovalDigestError} that leaves the vault untouched.
*/
readonly approvalDigest?: string;
/**
* Memory-format adapter (t_53f9f67f). Defaults to the Claude Code
* backend - byte-identical to the pre-seam behavior. Resolve via
* `resolveMemoryBackend()` to honor the `memory_backend` config key.
*/
readonly backend?: MemorySourceBackend;
}
export interface ImportClaudeMemoryResult {
readonly mode: "dry-run" | "apply";
readonly plans: ReadonlyArray<PlannedFile>;
readonly skipped: ReadonlyArray<{ basename: string; reason: string }>;
readonly conflicts: ReadonlyArray<PlannedFile>;
readonly applied: ReadonlyArray<PlannedFile>;
readonly skippedUnchanged: ReadonlyArray<PlannedFile>;
readonly snapshotRunId: string | null;
readonly localDate: string;
/**
* The seal of the adoption plan (t_18fda844): sha256 of the plans,
* skips, conflicts and unchanged rows - each plan row bound to the
* sha256 of its SOURCE entry and of its RENDERED body, clock fields
* normalized out of the latter (see {@link renderedBodySeal}) - via
* the integrity module's `sealWithDigest`. Wall-clock fields
* (`localDate`, the import timestamps) are deliberately OUTSIDE the
* sealed body, so a dry run and a later apply of the same content
* seal identically and an approval binds the plan, never the moment
* it was printed.
*/
readonly digest: string;
}
/**
* A plan row's content binding, sealed alongside the row: the sha256 of
* the SOURCE entry the row was parsed from and the sha256 of the RENDERED
* preference body the row would land, rendered under a fixed clock so the
* seal stays wall-clock-free.
*/
interface RenderedRowSeal {
readonly source_sha256: string;
readonly body_sha256: string;
}
/**
* The fixed clock the seal's render runs under. The rendered body embeds
* the run's clock (`created_at`, `unconfirmed_until`, `_imported_at`, the
* prose day); sealed as-written, a dry run and its later apply would seal
* differently on every tick and the approval could never carry. Re-
* rendered with both clock inputs pinned to this constant, the same
* content produces the same seal body whenever it is planned - while a
* source file rewritten between the two runs still changes the rendered
* body, which is the binding the approval exists for.
*/
const SEAL_RENDER_CLOCK = "1970-01-01T00:00:00Z";
/**
* The body an approval covers: what will land, what will not, and what
* refuses. The one spelling of "the plan", shared by the dry run that
* seals it and the apply that re-checks it. Each plan row carries its
* content binding ({@link RenderedRowSeal}) so a source file rewritten
* after the approved dry run no longer verifies, even when its action
* would come out the same.
*/
function planApprovalBody(parts: {
plans: ReadonlyArray<PlannedFile>;
skipped: ReadonlyArray<{ basename: string; reason: string }>;
conflicts: ReadonlyArray<PlannedFile>;
skippedUnchanged: ReadonlyArray<PlannedFile>;
seals: ReadonlyMap<string, RenderedRowSeal>;
}): Record<string, unknown> {
return {
conflicts: parts.conflicts,
plans: parts.plans.map((plan) => {
const seal = parts.seals.get(plan.basename);
return {
basename: plan.basename,
prefId: plan.prefId,
action: plan.action,
source_sha256: seal?.source_sha256 ?? null,
body_sha256: seal?.body_sha256 ?? null,
};
}),
skipped: parts.skipped,
skipped_unchanged: parts.skippedUnchanged,
};
}
/**
* The apply-time refusal when the plan an operator approved no longer
* matches the plan this run computed. Nothing has been written and no
* snapshot has been taken; the remedy is a fresh dry run, whose digest
* is what the next apply must carry.
*/
export class ApprovalDigestError extends Error {
/** The digest the caller asked to apply against. */
readonly approvalDigest: string;
/** The digest of the plan this run just computed. */
readonly planDigest: string;
constructor(approvalDigest: string, planDigest: string) {
super(
`approval digest mismatch: the plan changed since the approved dry run ` +
`(approved ${approvalDigest}, current plan ${planDigest}); nothing was written and ` +
"no snapshot was taken. Re-run `o2b brain import-claude-memory --dry-run` to review " +
"the current plan, then apply with its digest.",
);
this.name = "ApprovalDigestError";
this.approvalDigest = approvalDigest;
this.planDigest = planDigest;
}
}
/**
* Merge accumulated evidence fields from an existing preference file into a
* freshly-rendered preference body. Preserves the 8 fields that track
* evidence history so a re-import does not lose accumulated learning signals.
*
* Fields preserved: _applied_count, _violated_count, _evidenced_by,
* _last_evidence_at, _confirmed_at, unconfirmed_until, pinned, scope.
*
* Exported rather than copied because the continuity host-memory promotion
* renders through the same preference shape and must preserve the same
* evidence fields on UPDATE; a second copy of this decision is how the
* two UPDATE paths drift.
*/
export function mergePreservingEvidence(existingBody: string, freshBody: string): string {
const PRESERVED = [
"_applied_count",
"_violated_count",
"_evidenced_by",
"_last_evidence_at",
"_confirmed_at",
"unconfirmed_until",
"pinned",
"scope",
] as const;
// Extract key: value lines from existing frontmatter (between the --- fences).
const fmMatch = existingBody.match(/^---\n([\s\S]*?)\n---/);
if (!fmMatch) return freshBody;
const existingFm = fmMatch[1]!;
let result = freshBody;
for (const key of PRESERVED) {
// Match `key: <anything up to end-of-line>` (also handles array notation).
// Arrays in YAML inline form: `_evidenced_by: ['[[a.md]]', '[[b.md]]']`
const existingMatch = existingFm.match(new RegExp(`^${key}:(.*)$`, "m"));
if (!existingMatch) continue;
const existingLine = `${key}:${existingMatch[1]!}`;
// Replace the corresponding line in the fresh body.
result = result.replace(new RegExp(`^${key}:.*$`, "m"), existingLine);
}
return result;
}
export function importClaudeMemory(opts: ImportClaudeMemoryOpts): ImportClaudeMemoryResult {
// Vault-identity write guard (context-integrity-gates, Unit J). The
// dry-run form writes nothing, so it stays a read and is not gated -
// guarding a preview would refuse the very inspection an operator
// runs to decide whether the resolved vault is the intended one.
if (opts.mode === "apply") assertVaultIdentityForWrite(opts.vault);
const backend = opts.backend ?? claudeMemoryBackend;
assertSafeMemoryPath(opts.memoryDir, opts.allowArbitraryMemoryPath ?? false);
if (!existsSync(opts.memoryDir)) {
throw new Error(
`memory directory not found: ${homeRelativePath(opts.memoryDir)} ` +
`(pass --memory with an existing directory, or create it)`,
);
}
const now = opts.now ?? new Date();
const importedAt = isoSecond(now);
const localDate = importedAt.slice(0, 10);
// Every import lands under trial (t_sec_memory_trial): MEMORY.md is
// session-derived - agent-writable from conversation content - so a
// poisoned entry must not become a live rule on landing. Same window
// source as every first-party unconfirmed write, read fail-soft.
const unconfirmedUntil = isoSecond(addDays(now, unconfirmedWindowDays(opts.vault)));
const manifest = loadManifest(opts.vault);
const newImports: Record<string, { pref_id: string; sha256: string; imported_at: string }> = {
...manifest.imports,
};
const plans: PlannedFile[] = [];
// Store-only (task 2.10): the preferences are records of the store's
// fold, not pages under `Brain/`.
const storeOnly = preferencesStoreOnly(opts.vault);
const skipped: Array<{ basename: string; reason: string }> = [];
const filesToWrite: Array<{ plan: PlannedFile; body: string; sha256: string; slug: string }> = [];
// The content binding per plan row, keyed by the row's basename: the
// source entry's sha256 and the rendered body's sha256 (clock fields
// normalized out). Every plan row is pushed immediately after its
// render, so every row the seal below reads has an entry here.
const rowSeals = new Map<string, RenderedRowSeal>();
// Two MEMORY files with different basenames can slugify to the same
// preference id (e.g. `feedback_no_em_dashes.md` and
// `feedback no-em-dashes.md`). Without this guard, both would land
// `pref-no-em-dashes.md`, and the second `atomicWriteFileSync` would
// silently overwrite the first one. Track seen prefIds and route
// any duplicate into the skipped list with a clear reason.
const seenPrefIds = new Map<string, string>();
// A backend either walks a directory of per-memory files (Claude Code) or is
// pointed at a single export file that holds many records (mem0 / generic
// JSON). When `memoryDir` resolves to a file, that file is the sole input and
// its extension is trusted (the operator chose it); otherwise the backend's
// own `discoverMemoryFiles` selects the ingestible basenames.
const memIsFile = statSync(opts.memoryDir).isFile();
const baseDir = memIsFile ? dirname(opts.memoryDir) : opts.memoryDir;
const files = memIsFile
? [basename(opts.memoryDir)]
: backend.discoverMemoryFiles(opts.memoryDir);
for (const name of files) {
const text = readFileSync(join(baseDir, name), "utf8");
const entries = backend.parseMemoryEntries(text);
const multi = entries.length > 1;
entries.forEach((parsed, idx) => {
// The manifest/dedup key is the source basename for a single-entry file
// (byte-identical to the pre-seam Claude behavior) and `basename#slug`
// for one of many entries in a collection file, so a single JSON export
// maps to many preferences without colliding manifest rows.
if (parsed.kind === "skip") {
skipped.push({ basename: multi ? `${name}#${idx}` : name, reason: parsed.skipReason });
return;
}
const slug = backend.slugifyName(parsed.name);
const prefId = `pref-${slug}`;
const entryKey = multi ? `${name}#${slug}` : name;
const dupOf = seenPrefIds.get(prefId);
if (dupOf) {
skipped.push({
basename: entryKey,
reason: `duplicate target preference id ${prefId} (also produced by ${dupOf}); rename the memory entry to disambiguate`,
});
return;
}
// preferencePath adds pref- prefix itself, so pass just the slug
const prefFile = preferencePath(opts.vault, slug);
// Once switched the preference is a record of the store's fold, and
// its active and retired lives are one entry: a write would revive a
// retired one (an unswitched machine keeps the retired page apart).
const presence = storeOnly ? preferencePresence(opts.vault, slug) : null;
if (presence === "retired") {
skipped.push({
basename: entryKey,
reason: `a retired copy exists (ret-${slug}); restore or delete it first`,
});
return;
}
// Render BEFORE any plan row exists. A render that refuses THIS entry -
// a name whose slug fails the one shared tag rule, e.g. a purely
// numeric memory name (t_11ee559f) - is a per-entry data problem like a
// skip parse or a duplicate id: it lands a named skip row (file and
// rule both named) and the import continues. Rendering first keeps the
// refusal out of `plans`, so the sealed approval body never offers a
// file that would not land, and one legacy MEMORY file cannot abort the
// whole run with a message that names only the field.
let body: string;
const renderInput = {
name: parsed.name,
description: parsed.description,
body: parsed.body,
memoryPath: join(baseDir, name),
importedAt,
unconfirmedUntil,
bodySha256: parsed.bodySha256,
owner: resolvedOwnerFor(opts.vault, prefFile, undefined, undefined),
};
try {
// This module renders its own frontmatter and writes it with
// `atomicWriteFileSync`, so it never reaches `writePreference`
// and never got the ownership stamp every other preference
// writer applies (a-label-is-not-a-boundary, U3). Asking the
// shared resolver is the fix; rendering a second copy of the
// rule here is how the next writer would get it wrong again.
// `prefFile` is passed so an UPDATE carries the existing owner
// forward instead of re-owning the page, exactly as a rewrite
// through `writePreference` does.
body = backend.renderPreference(renderInput);
} catch (err) {
if (!(err instanceof TagSyntaxError)) throw err;
skipped.push({ basename: entryKey, reason: err.message });
return;
}
seenPrefIds.set(prefId, entryKey);
rowSeals.set(entryKey, {
source_sha256: parsed.bodySha256,
// The seal's render of the SAME entry under a fixed clock: the
// approval covers the content, never the moment.
body_sha256: sha256Hex(
backend.renderPreference({
...renderInput,
importedAt: SEAL_RENDER_CLOCK,
unconfirmedUntil: SEAL_RENDER_CLOCK,
}),
),
});
const manifestEntry = manifest.imports[entryKey];
const plan = planAction({
basename: entryKey,
prefId,
sha256: parsed.bodySha256,
inManifest: manifestEntry ? { sha256: manifestEntry.sha256 } : null,
prefExists: presence !== null ? presence === "active" : existsSync(prefFile),
});
plans.push(plan);
if (plan.action === "CREATE" || plan.action === "RECREATE" || plan.action === "UPDATE") {
filesToWrite.push({ plan, body, sha256: parsed.bodySha256, slug });
}
});
}
const conflicts = plans.filter((p) => p.action === "CONFLICT");
const skippedUnchanged = plans.filter((p) => p.action === "SKIP_UNCHANGED");
// Seal the adoption plan (t_18fda844). The apply below re-checks the
// operator's approval against THIS seal before the snapshot or any
// write, so what lands is what was approved or nothing is. Each row is
// sealed with its content binding, so a source file rewritten after the
// dry run fails the apply even when its plan action would come out the
// same.
const approvalBody = planApprovalBody({
plans,
skipped,
conflicts,
skippedUnchanged,
seals: rowSeals,
});
const planDigest = sealWithDigest(approvalBody).digest;
if (opts.mode === "dry-run") {
return {
mode: "dry-run",
plans,
skipped,
conflicts,
applied: [],
skippedUnchanged,
snapshotRunId: null,
localDate,
digest: planDigest,
};
}
// The approved plan is checked against the one just computed BEFORE
// the snapshot/write loop. Drift between dry run and apply is the
// case this exists for: a vault or memory source that moved in
// between must be re-reviewed, never written over.
if (opts.approvalDigest !== undefined && !digestVerifies(approvalBody, opts.approvalDigest)) {
throw new ApprovalDigestError(opts.approvalDigest, planDigest);
}
// §E design: process the non-conflict files first; throw `ConflictsError`
// at the end if any CONFLICT was detected. This matches design doc §E
// line "The run still processes the remaining files; final exit code is
// 0 only if every file is CREATE / UPDATE / RECREATE / SKIP_UNCHANGED."
// Caller (CLI) uses the thrown error to exit 2 while the applied side
// of the run still landed.
let snapshotRunId: string | null = null;
// Store-only: the append-only store needs no snapshot (design D14 item
// 9), and no page is written under `Brain/`.
if (filesToWrite.length > 0 && !storeOnly) {
// Through the gate rather than `createSnapshot`, so the archive obeys
// `snapshots.retention_count` like every other reason (it used to
// bypass retention). The gate derives the run id from the reason, so
// the archive's filename still cannot disagree with its provenance.
snapshotRunId = takeSnapshot(opts.vault, BRAIN_SNAPSHOT_REASON.importClaudeMemory, {
now,
}).runId;
}
const applied: PlannedFile[] = [];
if (filesToWrite.length > 0 && !storeOnly) {
mkdirSync(join(opts.vault, BRAIN_PREFERENCES_REL), { recursive: true });
}
for (const { plan, body: freshBody, sha256, slug } of filesToWrite) {
let finalBody = freshBody;
if (plan.action === "UPDATE") {
// Preserve evidence fields by merging frontmatter: the page, or the
// preference the store's fold holds once switched.
const existing = existingPreferencePageText(opts.vault, slug, (path) =>
readFileSync(path, "utf8"),
);
// Once switched, a preference the plan saw that is gone (or retired)
// since would lose its evidence under a fresh body, or be revived:
// the row is skipped, as the host-memory promotion skips it.
if (existing === null && storeOnly) {
skipped.push({
basename: plan.basename,
reason: `${plan.prefId} is no longer active; it was not rewritten`,
});
continue;
}
if (existing !== null) finalBody = mergePreservingEvidence(existing, freshBody);
}
// The page on an unswitched machine (plus the dual write), the
// preference's records only once switched.
writePreferencePageText(opts.vault, slug, finalBody);
newImports[plan.basename] = { pref_id: plan.prefId, sha256, imported_at: importedAt };
applied.push(plan);
}
// Only persist the manifest and emit a log event if the run actually
// did something (wrote files OR observed conflicts). A no-op apply
// (every plan SKIP_UNCHANGED, no conflicts) should not bloat the log.
const didSomething = applied.length > 0 || conflicts.length > 0;
if (didSomething) {
saveManifest(opts.vault, { version: 1, imports: newImports });
const counts = {
created: plans.filter((p) => p.action === "CREATE").length,
updated: plans.filter((p) => p.action === "UPDATE").length,
recreated: plans.filter((p) => p.action === "RECREATE").length,
skipped_unchanged: skippedUnchanged.length,
skipped_non_feedback: skipped.length,
conflicts: conflicts.length,
};
appendLogEvent(opts.vault, {
timestamp: importedAt,
eventType: BRAIN_LOG_EVENT_KIND.importClaudeMemory,
body: {
created: String(counts.created),
updated: String(counts.updated),
recreated: String(counts.recreated),
skipped_unchanged: String(counts.skipped_unchanged),
skipped_non_feedback: String(counts.skipped_non_feedback),
conflicts: String(counts.conflicts),
snapshot: snapshotRunId ?? "none",
agent: resolveAgentName(),
},
});
}
if (conflicts.length > 0) {
// Throw AFTER landing the safe writes so partial progress is preserved.
// The error carries the conflict list; the CLI prints them and exits 2.
throw new ConflictsError(conflicts, {
applied,
skipped,
skippedUnchanged,
snapshotRunId,
localDate,
});
}
return {
mode: "apply",
plans,
skipped,
conflicts,
applied,
skippedUnchanged,
snapshotRunId,
localDate,
digest: planDigest,
};
}
export interface ConflictsPartialProgress {
readonly applied: ReadonlyArray<PlannedFile>;
readonly skipped: ReadonlyArray<{ basename: string; reason: string }>;
readonly skippedUnchanged: ReadonlyArray<PlannedFile>;
readonly snapshotRunId: string | null;
readonly localDate: string;
}
export class ConflictsError extends Error {
readonly conflicts: ReadonlyArray<PlannedFile>;
readonly partial: ConflictsPartialProgress | null;
constructor(
conflicts: ReadonlyArray<PlannedFile>,
partial: ConflictsPartialProgress | null = null,
) {
super(`import-claude-memory: ${conflicts.length} conflict(s)`);
this.conflicts = conflicts;
this.partial = partial;
}
}
function addDays(date: Date, days: number): Date {
return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
}
/**
* The trial window an import grants, in days. Same source as every
* first-party unconfirmed write (`dream.unconfirmed_window_days`), read
* fail-soft for the same reason the restore's is: a vault with no
* readable `_brain.yaml` still gets the shipped default, not a live rule.
*/
function unconfirmedWindowDays(vault: string): number {
try {
return loadBrainConfig(vault).dream.unconfirmed_window_days;
} catch {
return DEFAULT_BRAIN_CONFIG.dream.unconfirmed_window_days;
}
}