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
23.2 KB
Raw Blame
/**
 * Capture-note contract (Knowledge intake suite, seam 1, t_f8f5ef6a).
 *
 * The contract owns the staging vocabulary shared by the inbound Telegram
 * capture bot (writer) and the inbox-drain pass (reader): the frontmatter
 * kind, provenance (source, sender, capture timestamp), the staging and
 * archive path helpers, and the read/write/list/archive functions.
 */

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

import {
  BRAIN_CAPTURE_KIND,
  CaptureContractError,
  archiveCapture,
  capturesSince,
  listStagedCaptures,
  readCaptureNote,
  readCatchupWatermark,
  writeCaptureNote,
  writeCatchupWatermark,
  type CaptureProvenance,
} from "../../../../src/core/brain/capture/capture-note.ts";
import { capturesDir, capturesProcessedDir } from "../../../../src/core/brain/paths.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-capture-note-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

function prov(overrides: Partial<CaptureProvenance> = {}): CaptureProvenance {
  return {
    source: "telegram",
    sender: "12345",
    capturedAt: "2026-07-19T12:00:00Z",
    ...overrides,
  };
}

test("writeCaptureNote stamps kind, provenance, and timestamp into staging", () => {
  const note = writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
  expect(note.staged).toBe(true);
  expect(note.provenance.source).toBe("telegram");
  expect(note.provenance.sender).toBe("12345");
  expect(note.provenance.capturedAt).toBe("2026-07-19T12:00:00Z");
  expect(note.body).toBe("capture a thought");
  expect(existsSync(join(vault, note.path))).toBe(true);
  expect(note.path.startsWith("Brain/captures/")).toBe(true);
  expect(note.id.startsWith("cap-")).toBe(true);
});

test("BRAIN_CAPTURE_KIND is the frontmatter kind marker", () => {
  expect(BRAIN_CAPTURE_KIND).toBe("brain-capture");
});

test("writeCaptureNote refuses an empty body with a typed error", () => {
  expect(() => writeCaptureNote(vault, { body: "   ", provenance: prov() })).toThrow(
    CaptureContractError,
  );
});

test("writeCaptureNote refuses empty provenance identity with a typed error", () => {
  expect(() => writeCaptureNote(vault, { body: "x", provenance: prov({ sender: "" }) })).toThrow(
    CaptureContractError,
  );
  expect(() => writeCaptureNote(vault, { body: "x", provenance: prov({ source: "" }) })).toThrow(
    CaptureContractError,
  );
});

test("listStagedCaptures returns staged captures sorted chronologically", () => {
  writeCaptureNote(vault, {
    body: "second",
    provenance: prov({ capturedAt: "2026-07-19T12:00:02Z" }),
  });
  writeCaptureNote(vault, {
    body: "first",
    provenance: prov({ capturedAt: "2026-07-19T12:00:01Z" }),
  });
  const staged = listStagedCaptures(vault);
  expect(staged.map((c) => c.body)).toEqual(["first", "second"]);
  expect(staged.every((c) => c.staged)).toBe(true);
});

test("archiveCapture moves a staged capture into the processed area", () => {
  const note = writeCaptureNote(vault, { body: "drain me", provenance: prov() });
  const archived = archiveCapture(vault, note.id);
  expect(archived.staged).toBe(false);
  expect(existsSync(join(vault, note.path))).toBe(false);
  expect(existsSync(join(vault, archived.path))).toBe(true);
  expect(archived.path.startsWith("Brain/captures/processed/")).toBe(true);
  expect(listStagedCaptures(vault)).toHaveLength(0);
});

test("archiveCapture on an unknown id is a typed error", () => {
  expect(() => archiveCapture(vault, "cap-2026-07-19-000000-deadbeef")).toThrow(
    CaptureContractError,
  );
});

test("capturesSince honours the watermark across staging and archive", () => {
  const a = writeCaptureNote(vault, {
    body: "a",
    provenance: prov({ capturedAt: "2026-07-19T12:00:01Z" }),
  });
  const b = writeCaptureNote(vault, {
    body: "b",
    provenance: prov({ capturedAt: "2026-07-19T12:00:02Z" }),
  });
  // Archiving must not hide a capture from catchup.
  archiveCapture(vault, a.id);
  expect(capturesSince(vault, null).map((c) => c.body)).toEqual(["a", "b"]);
  expect(capturesSince(vault, a.id).map((c) => c.body)).toEqual(["b"]);
  expect(capturesSince(vault, b.id)).toHaveLength(0);
});

test("catchup watermark round-trips and is absent by default", () => {
  expect(readCatchupWatermark(vault)).toBeNull();
  writeCatchupWatermark(vault, "cap-2026-07-19-120000-abcdabcd");
  expect(readCatchupWatermark(vault)).toBe("cap-2026-07-19-120000-abcdabcd");
});

test("path helpers resolve inside the Brain captures tree", () => {
  expect(capturesDir(vault).endsWith(join("Brain", "captures"))).toBe(true);
  expect(capturesProcessedDir(vault).endsWith(join("Brain", "captures", "processed"))).toBe(true);
});

test("writeCaptureNote retries a name lost between the probe and the create", () => {
  // Learn the name this capture allocates, then re-plant it as a dangling
  // symlink: `existsSync` follows the link and reads the name as free,
  // `link(2)` does not follow it and reports EEXIST. That is the pair of
  // answers the loser of a concurrent capture gets.
  const input = { body: "a raced capture", provenance: prov() };
  const first = writeCaptureNote(vault, input);
  const taken = join(vault, first.path);
  unlinkSync(taken);
  symlinkSync(join(capturesDir(vault), "never-created"), taken);

  const second = writeCaptureNote(vault, input);

  expect(second.id).toBe(`${first.id}-2`);
  expect(existsSync(join(vault, second.path))).toBe(true);
});

/**
 * Per-capture guidance (unit 3b / t_5e338af1).
 *
 * Claims pinned below:
 *
 *  1. Guidance round-trips verbatim through the `## Guidance` body section
 *     without leaking into the captured body.
 *  2. Two captures differing ONLY in guidance are two captures: the id hash
 *     reads the field, so they do not collapse into the `-2` allocator.
 *  3. A capture written without guidance keeps the historical id, byte for
 *     byte - the field is additive and the hash segment is conditional.
 *  4. A body that itself ends in a `## Guidance` heading is still read back
 *     as body, because the split is gated on the frontmatter marker rather
 *     than on finding the heading - and when the capture DOES carry
 *     guidance, the split takes the last separator, so the quoted section
 *     stays in the body and the writer's own guidance comes back whole.
 *  5. Empty or whitespace-only guidance is refused by name, never stored as
 *     an empty section.
 */

test("guidance round-trips verbatim and stays out of the body", () => {
  const written = writeCaptureNote(vault, {
    body: "capture a thought",
    provenance: prov(),
    guidance: "file this under research, not tasks",
  });
  expect(written.guidance).toBe("file this under research, not tasks");
  expect(written.body).toBe("capture a thought");

  const read = readCaptureNote(vault, written.id);
  expect(read).not.toBeNull();
  expect(read!.guidance).toBe("file this under research, not tasks");
  expect(read!.body).toBe("capture a thought");
});

test("a capture with no guidance reads back with none", () => {
  const written = writeCaptureNote(vault, { body: "plain", provenance: prov() });
  expect(written.guidance).toBeNull();
  expect(readCaptureNote(vault, written.id)!.guidance).toBeNull();
});

test("two captures differing only in guidance get distinct ids", () => {
  const a = writeCaptureNote(vault, {
    body: "same text",
    provenance: prov(),
    guidance: "route to inbox",
  });
  const b = writeCaptureNote(vault, {
    body: "same text",
    provenance: prov(),
    guidance: "route to archive",
  });
  expect(a.id).not.toBe(b.id);
  // Distinct by HASH, not by the collision allocator's numeric suffix.
  expect(b.id.endsWith("-2")).toBe(false);
});

test("adding guidance does not move the id of a capture that has none", () => {
  const plain = writeCaptureNote(vault, { body: "same text", provenance: prov() });
  rmSync(join(vault, plain.path));
  const again = writeCaptureNote(vault, { body: "same text", provenance: prov() });
  expect(again.id).toBe(plain.id);
});

test("a body that ends in its own Guidance heading is still all body", () => {
  const body = "notes\n\n## Guidance\n\nquoted from somewhere else";
  const written = writeCaptureNote(vault, { body, provenance: prov() });
  const read = readCaptureNote(vault, written.id)!;
  expect(read.guidance).toBeNull();
  expect(read.body).toBe(body);
});

test("a quoted Guidance section inside the body does not steal the real guidance", () => {
  // Both halves are present here: the body quotes a document that has its
  // own `## Guidance` heading, AND the capture carries guidance of its
  // own. The split has to take the LAST separator - the one the writer
  // appended - or the quotation's head becomes the instruction and the
  // rest of the quotation is lost from the body.
  const body = "notes\n\n## Guidance\n\nquoted from somewhere else";
  const written = writeCaptureNote(vault, {
    body,
    provenance: prov(),
    guidance: "file this under research",
  });
  const read = readCaptureNote(vault, written.id)!;
  expect(read.guidance).toBe("file this under research");
  expect(read.body).toBe(body);
});

test("empty guidance is refused by name rather than stored as an empty section", () => {
  expect(() =>
    writeCaptureNote(vault, { body: "text", provenance: prov(), guidance: "   " }),
  ).toThrow(CaptureContractError);
});

// ── t_151a564c: the stamped kind obeys a declared page_types vocabulary ──────

describe("writeCaptureNote — declared page_types vocabulary (t_151a564c)", () => {
  function writeConfig(pageTypes: string[] | null): void {
    if (pageTypes === null) return;
    writeFileSync(
      join(vault, "Brain", "_brain.yaml"),
      `schema:\n  page_types: [${pageTypes.join(", ")}]\n`,
      "utf8",
    );
  }

  test("a pack declaring page_types without brain-capture refuses before any file exists and before a name is consumed", () => {
    writeConfig(["note"]);
    let thrown: unknown;
    try {
      writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(CaptureContractError);
    // The refusal precedes every filesystem effect: the captures directory
    // is never created, so no file landed and no allocator name was consumed.
    expect(existsSync(capturesDir(vault))).toBe(false);
  });

  test("the refusal leaves an existing staging area untouched", () => {
    writeCaptureNote(vault, { body: "earlier capture", provenance: prov() });
    writeConfig(["note"]);
    expect(() => writeCaptureNote(vault, { body: "a second capture", provenance: prov() })).toThrow(
      CaptureContractError,
    );
    const staged = listStagedCaptures(vault);
    expect(staged).toHaveLength(1);
    expect(staged[0]!.body).toBe("earlier capture");
  });

  test("the refusal names the kind, the declared set, and the remedy", () => {
    writeConfig(["note"]);
    let thrown: unknown;
    try {
      writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
    } catch (err) {
      thrown = err;
    }
    const message = (thrown as CaptureContractError).message;
    expect(message).toContain("brain-capture");
    expect(message).toContain("note");
    expect(message).toContain("_brain.yaml");
  });

  test("a declared set containing brain-capture passes", () => {
    writeConfig(["note", "brain-capture"]);
    const note = writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
    expect(listStagedCaptures(vault)).toHaveLength(1);
    expect(readCaptureNote(vault, note.id)!.body).toBe("capture a thought");
  });

  test("absent config fails open with byte-identical output", () => {
    writeConfig(null);
    const open = writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
    const declaredVault = mkdtempSync(join(tmpdir(), "osb-capture-note-declared-"));
    try {
      mkdirSync(join(declaredVault, "Brain"), { recursive: true });
      writeFileSync(
        join(declaredVault, "Brain", "_brain.yaml"),
        "schema:\n  page_types: [note, brain-capture]\n",
        "utf8",
      );
      const gated = writeCaptureNote(declaredVault, {
        body: "capture a thought",
        provenance: prov(),
      });
      expect(readFileSync(join(vault, open.path), "utf8")).toBe(
        readFileSync(join(declaredVault, gated.path), "utf8"),
      );
    } finally {
      rmSync(declaredVault, { recursive: true, force: true });
    }
  });

  test("a config without a page_types declaration fails open", () => {
    writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema_version: 1\n", "utf8");
    const note = writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
    expect(readCaptureNote(vault, note.id)!.provenance.source).toBe("telegram");
  });

  test("the kind stays the frontmatter key and a refused-then-fixed capture reads back", () => {
    writeConfig(["note"]);
    expect(() =>
      writeCaptureNote(vault, { body: "capture a thought", provenance: prov() }),
    ).toThrow(CaptureContractError);
    // The operator declares the kind; the same capture now lands and the
    // contract's reader still round-trips it through the `kind` key.
    writeConfig(["note", "brain-capture"]);
    const note = writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
    const read = readCaptureNote(vault, note.id)!;
    expect(read.body).toBe("capture a thought");
    expect(read.provenance.capturedAt).toBe("2026-07-19T12:00:00Z");
  });
});

// ---------------------------------------------------------------------------
// Write-time marker neutralization (t_c2ac4fc8, lane A3). The capture seam
// neutralizes caller text under the gate's enforce mode and records the
// neutralized kinds in a conditional frontmatter key; off and shadow write
// byte-identical output.
// ---------------------------------------------------------------------------

import { createHash } from "node:crypto";
import { discoverMarkers } from "../../../../src/core/brain/inline.ts";
import {
  MARKDOWN_NEUTRALIZE_MODE_ENV,
  MarkdownNeutralizeModeError,
  detectMarkdownStructure,
} from "../../../../src/core/brain/text/neutralize-markdown.ts";
import { BRAIN_CAPTURES_REL } from "../../../../src/core/brain/paths.ts";

/** Set the gate mode env twin for one test, restoring it afterwards. */
function withGateMode(mode: string, run: () => void): void {
  const saved = process.env[MARKDOWN_NEUTRALIZE_MODE_ENV];
  process.env[MARKDOWN_NEUTRALIZE_MODE_ENV] = mode;
  try {
    run();
  } finally {
    if (saved === undefined) delete process.env[MARKDOWN_NEUTRALIZE_MODE_ENV];
    else process.env[MARKDOWN_NEUTRALIZE_MODE_ENV] = saved;
  }
}

/**
 * The id a fresh-vault capture of this text derives (captureBaseId's
 * contract: sha256 over source, sender, the TRIMMED body and the optional
 * guidance, first 8 hex; prefix `cap-<date>` keeps the date's dashes).
 */
function expectedId(body: string, guidance: string | null): string {
  const hash = createHash("sha256")
    .update(
      `telegram\u0000` +
        `12345\u0000` +
        `${body.trim()}` +
        (guidance === null ? "" : `\u0000${guidance}`),
      "utf8",
    )
    .digest("hex")
    .slice(0, 8);
  return `cap-2026-07-19-120000-${hash}`;
}

const MARKER_BODY = [
  "## Quoted",
  "",
  "see [[pref-target]] and [[pref-other|The Other]]",
  "",
  "@osb set note=[[x]] field=a value=b",
].join("\n");

test("gate off: a body full of live markers persists byte-identical to the legacy shape", () => {
  const note = writeCaptureNote(vault, { body: MARKER_BODY, provenance: prov() });
  const id = expectedId(MARKER_BODY, null);
  expect(note.id).toBe(id);
  expect(readFileSync(join(vault, note.path), "utf8")).toBe(
    [
      "---",
      "kind: brain-capture",
      `id: ${id}`,
      "capture_source: telegram",
      "capture_sender: 12345",
      'captured_at: "2026-07-19T12:00:00Z"',
      "tags: [brain, brain/capture]",
      "---",
      "",
      MARKER_BODY,
    ].join("\n") + "\n",
  );
});

test("gate shadow: bytes are unchanged and no provenance key is written", () => {
  withGateMode("shadow", () => {
    const note = writeCaptureNote(vault, { body: MARKER_BODY, provenance: prov() });
    const id = expectedId(MARKER_BODY, null);
    expect(readFileSync(join(vault, note.path), "utf8")).toBe(
      [
        "---",
        "kind: brain-capture",
        `id: ${id}`,
        "capture_source: telegram",
        "capture_sender: 12345",
        'captured_at: "2026-07-19T12:00:00Z"',
        "tags: [brain, brain/capture]",
        "---",
        "",
        MARKER_BODY,
        "",
      ].join("\n"),
    );
  });
});

test("gate enforce: planted markers are inert on disk and the kinds are recorded", () => {
  withGateMode("enforce", () => {
    const note = writeCaptureNote(vault, { body: MARKER_BODY, provenance: prov() });
    const raw = readFileSync(join(vault, note.path), "utf8");
    // The stored body is the post-neutralize text: no live structure per a
    // fence-masked scan of the persisted bytes.
    expect(detectMarkdownStructure(raw)).toEqual([]);
    expect(raw).toContain("\\[\\[pref-target\\]\\]");
    expect(raw).toContain("\\[\\[pref-other|The Other\\]\\]");
    expect(raw).toContain("\\#\\# Quoted");
    expect(raw).toContain("\\@osb set note=");
    // The conditional provenance key names the neutralized kinds, sorted.
    expect(raw).toContain("neutralized_markers: [atx-heading, osb-inline, wikilink]");
    // The reader hands back what was persisted, rendered as literal text.
    const read = readCaptureNote(vault, note.id)!;
    expect(read.body).toContain("\\[\\[pref-target\\]\\]");
    // Identity follows the persisted bytes.
    expect(note.id).toBe(expectedId(read.body, read.guidance));
  });
});

test("gate enforce: the guidance tail is neutralized and the writer's own split still works", () => {
  withGateMode("enforce", () => {
    const note = writeCaptureNote(vault, {
      body: "quotes a document\n\n## Guidance\n\nthe quoted fake section",
      guidance: "route to [[pref-sink]]",
      provenance: prov(),
    });
    const raw = readFileSync(join(vault, note.path), "utf8");
    // The caller-authored halves are inert; the page's ONE live heading
    // is the writer's own renderer-authored section heading.
    expect(raw).toContain("\\#\\# Guidance");
    expect(raw).toContain("\n\n## Guidance\n\n");
    expect(raw).toContain("route to \\[\\[pref-sink\\]\\]");
    expect(raw).toContain("neutralized_markers: [atx-heading, wikilink]");
    const read = readCaptureNote(vault, note.id)!;
    expect(detectMarkdownStructure(read.body)).toEqual([]);
    expect(detectMarkdownStructure(read.guidance!)).toEqual([]);
    // The split fires on the writer-set marker and never on the escaped one.
    expect(read.body).toBe("quotes a document\n\n\\#\\# Guidance\n\nthe quoted fake section");
    expect(read.guidance).toBe("route to \\[\\[pref-sink\\]\\]");
  });
});

test("gate enforce: a fence split across the body-guidance boundary cannot plant a live marker", () => {
  withGateMode("enforce", () => {
    // The reviewer's concrete fixture: the body's trailing fence opens an
    // unterminated fence the guidance's own fence line closes on the
    // rendered page, which left the planted marker LIVE for every marker
    // scanner while both halves scanned clean on their own.
    const note = writeCaptureNote(vault, {
      body: "x\n```",
      guidance: "```\n@osb feedback negative topic=t principle=p",
      provenance: prov(),
    });
    const raw = readFileSync(join(vault, note.path), "utf8");
    // The rendered page bytes carry no live marker ...
    expect(discoverMarkers(raw)).toHaveLength(0);
    expect(raw).toContain("\\@osb feedback negative topic=t principle=p");
    // ... and the conditional provenance key names what was escaped.
    expect(raw).toContain("neutralized_markers: [osb-inline]");
    // The writer's own heading is never escaped: only the caller halves pass
    // through the neutralizer.
    expect(raw).toContain("\n\n## Guidance\n\n");
    const read = readCaptureNote(vault, note.id)!;
    expect(read.body).toBe("x\n```");
    expect(read.guidance).toBe("```\n\\@osb feedback negative topic=t principle=p");
  });
});

test("gate enforce: a marker the split fence masks on the page stays untouched in both halves", () => {
  withGateMode("enforce", () => {
    // Consistency direction: the body's fence never closes, so the combined
    // page's scanner parses nothing from the guidance - the fence masks the
    // marker there just as it masks it in the threaded half, and the write
    // stays byte-identical with no provenance key.
    const note = writeCaptureNote(vault, {
      body: "x\n```",
      guidance: "@osb feedback negative topic=t principle=p",
      provenance: prov(),
    });
    const raw = readFileSync(join(vault, note.path), "utf8");
    expect(discoverMarkers(raw)).toHaveLength(0);
    expect(raw).toContain("\n@osb feedback negative topic=t principle=p");
    expect(rawHasNeutralizedKey(join(vault, note.path))).toBe(false);
  });
});

test("gate enforce: a clean body gains zero bytes", () => {
  withGateMode("enforce", () => {
    const note = writeCaptureNote(vault, { body: "capture a thought", provenance: prov() });
    const id = expectedId("capture a thought", null);
    expect(readFileSync(join(vault, note.path), "utf8")).toBe(
      [
        "---",
        "kind: brain-capture",
        `id: ${id}`,
        "capture_source: telegram",
        "capture_sender: 12345",
        'captured_at: "2026-07-19T12:00:00Z"',
        "tags: [brain, brain/capture]",
        "---",
        "",
        "capture a thought",
        "",
      ].join("\n"),
    );
    expect(rawHasNeutralizedKey(join(vault, note.path))).toBe(false);
  });
});

function rawHasNeutralizedKey(path: string): boolean {
  return readFileSync(path, "utf8").includes("neutralized_markers:");
}

test("gate enforce: re-capture of the same text under a stable gate is idempotent", () => {
  withGateMode("enforce", () => {
    const first = writeCaptureNote(vault, { body: MARKER_BODY, provenance: prov() });
    const second = writeCaptureNote(vault, { body: MARKER_BODY, provenance: prov() });
    // Same text, same provenance, same gate: the same derived stem - the
    // allocator's exclusive-create suffix is the only difference.
    expect(second.id.startsWith(`${first.id}-`)).toBe(true);
    const firstRaw = readFileSync(join(vault, first.path), "utf8");
    const secondRaw = readFileSync(join(vault, second.path), "utf8");
    expect(secondRaw).toBe(firstRaw.replace(`id: ${first.id}`, `id: ${second.id}`));
  });
});

test("a misconfigured gate mode is refused before any filesystem effect", () => {
  withGateMode("sometimes", () => {
    expect(() =>
      writeCaptureNote(vault, { body: "capture a thought", provenance: prov() }),
    ).toThrow(MarkdownNeutralizeModeError);
    expect(existsSync(join(vault, "Brain", "captures"))).toBe(false);
  });
});

test("the staging area is where neutralized captures land", () => {
  withGateMode("enforce", () => {
    const note = writeCaptureNote(vault, { body: MARKER_BODY, provenance: prov() });
    expect(note.path.startsWith(`${BRAIN_CAPTURES_REL}/`)).toBe(true);
    expect(note.staged).toBe(true);
  });
});