Skip to content

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
22.4 KB
Raw Blame
/**
 * `promoteHostMemory` - the host-memory readback path (issue #277):
 * continuity `host_memory_write` records re-rendered as unconfirmed
 * preference pages, dry-run first, sealed with an approval digest.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { appendContinuityRecord } from "../../../../src/core/brain/continuity/store.ts";
import {
  PromoteApprovalDigestError,
  PromoteConflictsError,
  PromoteManifestCorruptError,
  promoteHostMemory,
} from "../../../../src/core/brain/continuity/promote-host-memory.ts";
import { REDACTION_PLACEHOLDER, redactStructured } from "../../../../src/core/redactor.ts";
import { loadPromotionsManifest } from "../../../../src/core/brain/host-memory-promotions.ts";
import {
  HOST_MEMORY_WRITE_KIND,
  recordHostMemoryWrite,
} from "../../../../src/core/brain/host-memory-write.ts";
import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import { brainConfigPath, preferencePath, retiredPath } from "../../../../src/core/brain/paths.ts";
import { loadBrainConfig } from "../../../../src/core/brain/policy.ts";
import { resolvedOwnerFor } from "../../../../src/core/brain/preference.ts";
import { isoSecond } from "../../../../src/core/brain/time.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
import { sha256Hex } from "../../../../src/core/integrity/digest.ts";
import {
  FAKE_PROVIDER_KEY,
  FAKE_VENDOR_KEY,
  fakeCredential,
} from "../../../helpers/fake-credentials.ts";
import { useUnshardedLegacyLog } from "../../../helpers/device-id.ts";

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

let vault: string;
let savedEnv: Record<string, string | undefined>;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-promote-host-memory-"));
  bootstrapBrain(vault);
  savedEnv = { VAULT_AGENT_NAME: process.env["VAULT_AGENT_NAME"] };
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
  for (const [key, value] of Object.entries(savedEnv)) {
    if (value === undefined) delete process.env[key];
    else process.env[key] = value;
  }
});

const NOW = new Date("2026-07-01T12:00:00Z");
const promotionsJson = () => join(vault, "Brain", ".imports", "host-memory-promotions.json");

/** A private-page fixture body: the text lives only inside the private region. */
const PRIVATE_BODY = "quiet retirement plan";

function hostRef(recordId: string): string {
  return `hostmem-${recordId.slice(-12).toLowerCase()}`;
}

/** Snapshot archives this feature has taken, by run-id prefix. */
function promoteSnapshots(): string[] {
  return readdirSync(join(vault, "Brain", ".snapshots"))
    .filter((name) => name.startsWith("promote-host-memory-"))
    .toSorted();
}

function writeHostMemory(content: string, createdAt = "2026-06-20T10:00:00Z") {
  return recordHostMemoryWrite(vault, { action: "add", target: "user", content, createdAt });
}

/**
 * Seed a ledger row with an exact id, bypassing the store's content-hash
 * dedup - the only way to pin a slug-tail collision fixture.
 */
function writeRawHostRecord(id: string, content: string, createdAt = "2026-06-20T10:00:00Z") {
  const dir = join(vault, "Brain", "log", "continuity");
  mkdirSync(dir, { recursive: true });
  const row = {
    schema: "o2b.continuity.v1",
    id,
    kind: "host_memory_write",
    createdAt,
    sourceRefs: [],
    payload: { action: "add", target: "user", content },
    private: false,
    redacted: false,
  };
  writeFileSync(join(dir, "2026-06.jsonl"), `${JSON.stringify(row)}\n`, { flag: "a" });
}

function writeRawHostRecordWithCreatedAt(id: string, content: string, createdAt: string) {
  writeRawHostRecord(id, content, createdAt);
}

function promotionOf(recordId: string) {
  return loadPromotionsManifest(vault).promotions[recordId];
}

describe("promoteHostMemory", () => {
  test("dry-run plans and writes nothing", () => {
    const record = writeHostMemory("User prefers dark mode");
    const res = promoteHostMemory({ vault, mode: "dry-run", now: NOW });

    expect(res.mode).toBe("dry-run");
    expect(res.total).toBe(1);
    expect(res.plans.map((p) => p.action)).toEqual(["CREATE"]);
    expect(res.plans[0]!.basename).toBe(record.id);
    expect(res.plans[0]!.prefId).toBe(`pref-${hostRef(record.id)}`);
    expect(res.digest).toMatch(/^[0-9a-f]{64}$/);
    expect(existsSync(preferencePath(vault, hostRef(record.id)))).toBe(false);
    expect(existsSync(promotionsJson())).toBe(false);
    expect(promoteSnapshots()).toEqual([]);
  });

  test("apply creates a page under the trial window with ledger provenance", () => {
    const record = writeHostMemory("User prefers dark mode");
    const windowDays = loadBrainConfig(vault).dream.unconfirmed_window_days;
    const expectedUntil = isoSecond(new Date(NOW.getTime() + windowDays * 24 * 60 * 60 * 1000));
    const owner = resolvedOwnerFor(
      vault,
      preferencePath(vault, hostRef(record.id)),
      undefined,
      undefined,
    );

    const res = promoteHostMemory({ vault, mode: "apply", now: NOW });
    expect(res.applied).toHaveLength(1);
    expect(res.snapshotRunId).not.toBeNull();

    // The target page is named for the record, and the renderer derives
    // the frontmatter id and topic from the SAME record-derived identity,
    // so an id-keyed lookup lands on the file that exists.
    const page = readFileSync(preferencePath(vault, hostRef(record.id)), "utf8");
    expect(page).toContain(`id: pref-${hostRef(record.id)}`);
    expect(page).toContain(`unconfirmed_until: "${expectedUntil}"`);
    expect(page).toContain("_status: unconfirmed");
    // Provenance names the ledger shard and the record id itself.
    expect(page).toContain('_imported_from: "Brain/log/continuity/2026-06.jsonl"');
    expect(page).toContain(`host memory write \`${record.id}\``);
    expect(page).toContain("User prefers dark mode");
    // Owner wiring follows the shared resolver: a line when the gate
    // stamps one, none when it is off.
    if (owner === undefined) expect(page).not.toContain("owner:");
    else expect(page).toContain(`owner: ${owner}`);

    const manifest = promotionOf(record.id);
    expect(manifest?.pref_id).toBe(res.plans[0]!.prefId);
    expect(manifest?.sha256).toBe(sha256Hex("User prefers dark mode"));
    expect(manifest?.promoted_at).toBe("2026-07-01T12:00:00Z");
  });

  test("the trial window reads the vault config", () => {
    const record = writeHostMemory("User prefers dark mode");
    atomicWriteFileSync(
      brainConfigPath(vault),
      "schema_version: 1\ndream:\n  unconfirmed_window_days: 3\n",
    );
    promoteHostMemory({ vault, mode: "apply", now: NOW });
    const page = readFileSync(preferencePath(vault, hostRef(record.id)), "utf8");
    expect(page).toContain('unconfirmed_until: "2026-07-04T12:00:00Z"');
  });

  test("the owner stamp lands when the delivery gate is on", () => {
    process.env["VAULT_AGENT_NAME"] = "promote-agent";
    atomicWriteFileSync(
      brainConfigPath(vault),
      "schema_version: 1\nintegrity:\n  owner_scope_delivery: warn\n",
    );
    const record = writeHostMemory("User prefers dark mode");
    promoteHostMemory({ vault, mode: "apply", now: NOW });
    const page = readFileSync(preferencePath(vault, hostRef(record.id)), "utf8");
    expect(page).toContain("owner: promote-agent");
  });

  test("a second run over unchanged content plans SKIP_UNCHANGED and writes nothing", () => {
    const record = writeHostMemory("User prefers dark mode");
    promoteHostMemory({ vault, mode: "apply", now: NOW });
    const prefFile = preferencePath(vault, hostRef(record.id));
    const pageBefore = readFileSync(prefFile, "utf8");

    const second = promoteHostMemory({
      vault,
      mode: "apply",
      now: new Date("2026-07-02T12:00:00Z"),
    });
    expect(second.plans.map((p) => p.action)).toEqual(["SKIP_UNCHANGED"]);
    expect(second.applied).toHaveLength(0);
    expect(second.skippedUnchanged).toHaveLength(1);
    expect(second.snapshotRunId).toBeNull();

    expect(readFileSync(prefFile, "utf8")).toBe(pageBefore);
    // The sidecar records the FIRST landing; a no-op run does not touch it.
    expect(promotionOf(record.id)?.promoted_at).toBe("2026-07-01T12:00:00Z");
  });

  test("a page on disk with no promotion history plans CONFLICT; apply still lands the rest", () => {
    const first = writeHostMemory("User prefers dark mode", "2026-06-20T10:00:00Z");
    const second = writeHostMemory("User signs commits", "2026-06-21T10:00:00Z");
    // The conflict fixture: the second page exists with no sidecar entry
    // behind it, as if written by another writer.
    writeFileSync(
      preferencePath(vault, hostRef(second.id)),
      "---\nkind: brain-preference\n---\n\nhand-written\n",
      "utf8",
    );

    let thrown: PromoteConflictsError | undefined;
    try {
      promoteHostMemory({ vault, mode: "apply", now: NOW });
    } catch (err) {
      if (err instanceof PromoteConflictsError) thrown = err;
    }
    expect(thrown).toBeDefined();
    expect(thrown!.conflicts.map((c) => c.basename)).toEqual([second.id]);
    expect(thrown!.partial).not.toBeNull();
    expect(thrown!.partial!.applied.map((p) => p.basename)).toEqual([first.id]);
    expect(existsSync(preferencePath(vault, hostRef(first.id)))).toBe(true);
    // The conflicting page is left exactly as it was found.
    expect(readFileSync(preferencePath(vault, hostRef(second.id)), "utf8")).toContain(
      "hand-written",
    );
  });

  test("UPDATE re-renders the page and preserves accumulated evidence fields", () => {
    const record = writeHostMemory("User prefers dark mode");
    promoteHostMemory({ vault, mode: "apply", now: NOW });
    const prefFile = preferencePath(vault, hostRef(record.id));

    // Simulate accumulated evidence.
    const pref = readFileSync(prefFile, "utf8");
    writeFileSync(
      prefFile,
      pref
        .replace("_applied_count: 0", "_applied_count: 7")
        .replace("_evidenced_by: []", "_evidenced_by: ['[[a.md]]']"),
      "utf8",
    );

    // The ledger is append-only and a record id is derived from its
    // content, so content for an existing id cannot honestly change. The
    // reachable UPDATE is a stale sidecar sha - a manifest hand-merged
    // across devices - which is exactly the drift the branch exists for.
    const manifest = JSON.parse(readFileSync(promotionsJson(), "utf8")) as {
      promotions: Record<string, { sha256: string }>;
    };
    manifest.promotions[record.id]!.sha256 = sha256Hex("stale");
    atomicWriteFileSync(promotionsJson(), JSON.stringify(manifest, null, 2) + "\n");

    const res = promoteHostMemory({ vault, mode: "apply", now: new Date("2026-07-01T12:00:01Z") });
    expect(res.plans.map((p) => p.action)).toEqual(["UPDATE"]);
    const after = readFileSync(prefFile, "utf8");
    expect(after).toContain("_applied_count: 7");
    expect(after).toContain("_evidenced_by: ['[[a.md]]']");
    expect(after).toContain("User prefers dark mode");
  });

  test("private records never promote and are counted through the store door", () => {
    writeHostMemory(`note <private>${PRIVATE_BODY}</private> end`);
    const res = promoteHostMemory({ vault, mode: "dry-run", now: NOW });

    expect(res.total).toBe(1);
    expect(res.privateCount).toBe(1);
    expect(res.plans).toHaveLength(0);
    expect(res.skipped).toHaveLength(0);
    expect(JSON.stringify(res)).not.toContain(PRIVATE_BODY);
    // Nothing landed: the preferences directory holds no hostmem page.
    expect(
      readdirSync(join(vault, "Brain", "preferences")).filter((name) =>
        name.startsWith("pref-hostmem-"),
      ),
    ).toEqual([]);
  });

  test("a redacted record promotes its masked text and is counted", () => {
    // Write-time redaction (the redactor's default options) masks a
    // key=value credential shape; a bare vendor token is NOT masked at
    // write time - that tighter pass is the export boundary's, per the
    // export verb's own docblock.
    const record = writeHostMemory(`token=${FAKE_PROVIDER_KEY} for the staging deploy`);
    expect(record.redacted).toBe(true);
    expect(record.private).toBe(false);

    const res = promoteHostMemory({ vault, mode: "apply", now: NOW });
    expect(res.redactedCount).toBe(1);
    expect(res.applied).toHaveLength(1);
    const page = readFileSync(preferencePath(vault, hostRef(record.id)), "utf8");
    expect(page).toContain("token=***REDACTED***");
    expect(page).not.toContain(FAKE_PROVIDER_KEY);
  });

  test("empty content is skipped by name", () => {
    const record = appendContinuityRecord(vault, {
      kind: HOST_MEMORY_WRITE_KIND,
      createdAt: "2026-06-20T10:00:00Z",
      payload: { action: "add", target: "user", content: "   " },
    });
    const res = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    expect(res.skipped).toEqual([{ id: record.id, reason: "empty content" }]);
    expect(res.plans).toHaveLength(0);
  });

  test("--month selects exactly the month's window", () => {
    writeHostMemory("June fact", "2026-06-20T10:00:00Z");
    const july = writeHostMemory("July fact", "2026-07-01T09:00:00Z");
    const privateJuly = appendContinuityRecord(vault, {
      kind: HOST_MEMORY_WRITE_KIND,
      createdAt: "2026-07-02T09:00:00Z",
      payload: { action: "add", target: "user", content: `x <private>${PRIVATE_BODY}</private>` },
    });

    const res = promoteHostMemory({ vault, mode: "dry-run", month: "2026-06", now: NOW });
    expect(res.total).toBe(1);
    expect(res.plans).toHaveLength(1);
    expect(res.plans.map((p) => p.basename)).not.toContain(july.id);
    expect(res.plans.map((p) => p.basename)).not.toContain(privateJuly.id);
    expect(res.privateCount).toBe(0);
  });

  test("an approval digest mismatch throws and writes nothing", () => {
    const record = writeHostMemory("User prefers dark mode");
    const dry = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    // The ledger moves between the approved dry run and the apply.
    writeHostMemory("A later fact", "2026-06-21T10:00:00Z");

    expect(() =>
      promoteHostMemory({ vault, mode: "apply", approvalDigest: dry.digest, now: NOW }),
    ).toThrow(PromoteApprovalDigestError);
    try {
      promoteHostMemory({ vault, mode: "apply", approvalDigest: dry.digest, now: NOW });
    } catch (err) {
      // The remedy must be a command that exists: the verb has no
      // --dry-run flag, the default IS the dry run (M5).
      expect((err as Error).message).toContain("(the default is the dry run)");
      expect((err as Error).message).not.toContain("--dry-run");
    }
    expect(existsSync(preferencePath(vault, hostRef(record.id)))).toBe(false);
    expect(promoteSnapshots()).toEqual([]);
    expect(promotionOf(record.id)).toBeUndefined();

    // The fresh digest the new dry run prints is what the next apply takes.
    const fresh = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    expect(fresh.digest).not.toBe(dry.digest);
    const applied = promoteHostMemory({
      vault,
      mode: "apply",
      approvalDigest: fresh.digest,
      now: NOW,
    });
    expect(applied.applied).toHaveLength(2);
  });

  test("apply without a digest works - the interactive path", () => {
    writeHostMemory("User prefers dark mode");
    const res = promoteHostMemory({ vault, mode: "apply", now: NOW });
    expect(res.applied).toHaveLength(1);
    expect(existsSync(preferencePath(vault, hostRef(res.applied[0]!.basename)))).toBe(true);
  });

  test("a purely numeric first line still lands - the record-derived identity carries the tag rule", () => {
    // Obsidian tags may carry digits but may not be ONLY digits. The
    // page's topic comes from the record id, never the display text, so
    // a numeric first line cannot break the tag rule; it rides along as
    // the `principle` display text.
    writeHostMemory("42");
    const res = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    expect(res.plans.map((p) => p.action)).toEqual(["CREATE"]);
    expect(res.skipped).toHaveLength(0);
    const recordId = res.plans[0]!.basename;
    promoteHostMemory({ vault, mode: "apply", now: NOW });
    const page = readFileSync(preferencePath(vault, hostRef(recordId)), "utf8");
    expect(page).toContain(`topic: ${hostRef(recordId)}`);
    expect(page).toContain('principle: "42"');
  });

  test("two records whose hash tails collide plan onto one named skip, not one overwrite", () => {
    // The store derives ids from content, so the collision fixture seeds
    // raw ledger rows whose ids deliberately share a 12-character tail.
    const shared = "aaaaaaaaaaaaaaaa";
    writeRawHostRecord(`ctn_20260620000000_${shared}`, "First fact");
    writeRawHostRecord(`ctn_20260621000000_${shared}`, "Second fact");
    const res = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    expect(res.plans).toHaveLength(1);
    expect(res.skipped).toHaveLength(1);
    expect(res.skipped[0]!.reason).toContain("already claimed by record");
  });

  test("a retired page is never resurrected by a re-run", () => {
    const record = writeHostMemory("User prefers dark mode");
    promoteHostMemory({ vault, mode: "apply", now: NOW });
    // The operator (or the dream pass) retires the promoted page.
    renameSync(preferencePath(vault, hostRef(record.id)), retiredPath(vault, hostRef(record.id)));

    const res = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    expect(res.plans).toHaveLength(0);
    expect(res.skipped).toHaveLength(1);
    expect(res.skipped[0]!.reason).toContain("retired copy exists");
    expect(existsSync(preferencePath(vault, hostRef(record.id)))).toBe(false);
  });

  test("apply writes the promote-host-memory snapshot and log event", () => {
    writeHostMemory("User prefers dark mode");
    const res = promoteHostMemory({ vault, mode: "apply", now: NOW });

    expect(res.snapshotRunId).not.toBeNull();
    expect(res.snapshotRunId!).toStartWith("promote-host-memory-");
    const snapshots = readdirSync(join(vault, "Brain", ".snapshots"));
    expect(snapshots.some((name) => name.startsWith("promote-host-memory-"))).toBe(true);

    const log = readFileSync(join(vault, "Brain", "log", `${res.localDate}.md`), "utf8");
    expect(log).toContain("promote-host-memory");
    expect(log).toContain("created: 1");
    expect(log).toContain("private_dropped: 0");
    expect(log).toContain("redacted: 0");
  });

  test("credential-shaped content is re-scanned and lands masked (review H1)", () => {
    const urlCred = `postgres://deploy:${fakeCredential("Hunter2", "-Fake")}@db.example.test:5432/app`;
    const content = `DB is ${urlCred} and the key is ${FAKE_VENDOR_KEY}`;
    const record = writeHostMemory(content);
    const res = promoteHostMemory({ vault, mode: "apply", now: NOW });

    // The write-time flag stays false (the ledger redacts under the loose
    // defaults), and the strict re-scan is what caught these.
    expect(record.redacted).toBe(false);
    expect(res.redactedCount).toBe(1);

    const masked = redactStructured(content, {
      redactTokens: true,
      redactUrlCredentials: true,
    }).value as string;
    const page = readFileSync(preferencePath(vault, hostRef(record.id)), "utf8");
    expect(page).not.toContain(FAKE_VENDOR_KEY);
    expect(page).not.toContain("Hunter2-Fake");
    expect(page).toContain(REDACTION_PLACEHOLDER);
    // The plan binding covers the masked text: the sidecar's sha is the
    // sha of what landed, so a re-run stays idempotent.
    expect(promotionOf(record.id)?.sha256).toBe(sha256Hex(masked));
    expect(page).toContain(masked.split("\n")[0]!.slice(0, 20));
  });

  test("a malformed row skips by name and never aborts the run (review M1)", () => {
    const good = writeHostMemory("User prefers dark mode", "2026-06-20T10:00:00Z");
    writeRawHostRecordWithCreatedAt(
      "ctn_20260622000000_feeddadfeeddad0",
      "Bad date row",
      "June 23",
    );
    writeRawHostRecord("ctn_20260623!:000000_feeddadfeeddad1", "Bad id row");
    const res = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    expect(res.plans.map((p) => p.action)).toEqual(["CREATE"]);
    expect(res.plans[0]!.basename).toBe(good.id);
    const reasons = res.skipped.map((s) => s.reason).toSorted();
    expect(reasons).toEqual(["non-canonical createdAt", "non-canonical record id"]);
  });

  test("a corrupt promotion manifest is reported on dry run and refused on apply (review M3)", () => {
    writeHostMemory("User prefers dark mode");
    mkdirSync(join(vault, "Brain", ".imports"), { recursive: true });
    writeFileSync(
      join(vault, "Brain", ".imports", "host-memory-promotions.json"),
      '{"version": 1, "promotions": {"ctn_2026',
      "utf8",
    );
    const dry = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    expect(dry.manifestCorrupt).toBe(true);
    // The plan computed against the empty history names the loss: the
    // landed page (none here) would show CONFLICT, the row plans CREATE.
    expect(dry.plans.map((p) => p.action)).toEqual(["CREATE"]);

    expect(() => promoteHostMemory({ vault, mode: "apply", now: NOW })).toThrow(
      PromoteManifestCorruptError,
    );
    expect(promoteSnapshots()).toEqual([]);
    // The garbage file is not flattened to an empty set by the run.
    expect(
      readFileSync(join(vault, "Brain", ".imports", "host-memory-promotions.json"), "utf8"),
    ).toBe('{"version": 1, "promotions": {"ctn_2026');
  });

  test("identical content from repeated writes promotes once (review M4)", () => {
    writeHostMemory("User prefers dark mode", "2026-06-20T10:00:00Z");
    writeHostMemory("User prefers dark mode", "2026-06-21T10:00:00Z");
    writeHostMemory("User prefers dark mode", "2026-06-22T10:00:00Z");
    const res = promoteHostMemory({ vault, mode: "apply", now: NOW });
    expect(res.plans).toHaveLength(1);
    expect(res.skipped).toHaveLength(2);
    for (const skip of res.skipped) {
      expect(skip.reason).toMatch(/^same content as record ctn_/);
    }
    const pages = readdirSync(join(vault, "Brain", "preferences")).filter((name) =>
      name.startsWith("pref-hostmem-"),
    );
    expect(pages).toHaveLength(1);
  });

  test("the same content seals identically across runs - the approval binds the plan", () => {
    writeHostMemory("User prefers dark mode");
    const first = promoteHostMemory({ vault, mode: "dry-run", now: NOW });
    const second = promoteHostMemory({
      vault,
      mode: "dry-run",
      now: new Date("2026-08-15T08:30:00Z"),
    });
    expect(second.digest).toBe(first.digest);
    expect(second.localDate).toBe("2026-08-15");
  });
});