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
5.8 KB
Raw Blame
/**
 * `buildBacklinkIndex`'s two U3 obligations (a-label-is-not-a-boundary).
 *
 * 1. An optional owner scope, second parameter, that drops refs whose
 *    SOURCE artifact the scope may not see. Nine existing call sites pass
 *    nothing and keep the index they always got.
 * 2. An artifact the collector cannot parse is REPORTED. The `catch {
 *    continue; }` this replaced returned a confident `count: 0` on a
 *    vault whose preferences use the un-prefixed Group C frontmatter
 *    shape, and the caller had no way to tell that from a genuine zero.
 */

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

import { buildBacklinkIndex } from "../../../src/core/brain/backlinks.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { pinHome } from "../../helpers/temp-dir.ts";

/** Pinned per file; nothing in this repository pins it globally. */
pinHome("o2b-backlinks-scope-home-");

const OWNER_A = "agent-a";
const OWNER_B = "agent-b";
const TARGET = "pref-shared";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-backlinks-scope-vault-"));
  for (const sub of ["preferences", "retired", "inbox", "processed", "log"]) {
    mkdirSync(join(vault, "Brain", sub), { recursive: true });
  }
});

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

/**
 * A preference in the CURRENT frontmatter shape (`_`-prefixed Group C
 * keys), optionally owner-tagged.
 */
function writePref(slug: string, owner: string | null, body: string): void {
  writeFileSync(
    join(brainDirs(vault).preferences, `pref-${slug}.md`),
    [
      "---",
      "kind: brain-preference",
      `id: pref-${slug}`,
      ...(owner === null ? [] : [`owner: ${owner}`]),
      "created_at: 2026-05-01T00:00:00Z",
      "unconfirmed_until: 2026-05-08T00:00:00Z",
      "tags: []",
      `topic: ${slug}`,
      `principle: principle for ${slug}`,
      "_status: confirmed",
      "_confirmed_at: 2026-05-02T00:00:00Z",
      "_evidenced_by: []",
      "_applied_count: 0",
      "_violated_count: 0",
      "---",
      "",
      body,
      "",
    ].join("\n"),
  );
}

/**
 * The Group C shape a legacy vault carries: `status:` un-prefixed.
 * `normalizeDerivedKeys` throws on it, which is what the collector used
 * to swallow.
 */
function writeLegacyPref(slug: string, body: string): void {
  writeFileSync(
    join(brainDirs(vault).preferences, `pref-${slug}.md`),
    [
      "---",
      "kind: brain-preference",
      `id: pref-${slug}`,
      "created_at: 2026-05-01T00:00:00Z",
      "unconfirmed_until: 2026-05-08T00:00:00Z",
      "tags: []",
      `topic: ${slug}`,
      `principle: principle for ${slug}`,
      "status: confirmed",
      "_status: confirmed",
      "---",
      "",
      body,
      "",
    ].join("\n"),
  );
}

test("an owner scope drops refs written by another owner's artifact", () => {
  writePref("shared", null, "the target");
  writePref("owned-by-a", OWNER_A, `points at [[${TARGET}]]`);
  writePref("also-shared", null, `points at [[${TARGET}]]`);

  const unscoped = buildBacklinkIndex(vault);
  expect((unscoped.get(TARGET) ?? []).map((r) => r.source).toSorted()).toEqual([
    "pref-also-shared",
    "pref-owned-by-a",
  ]);

  const scoped = buildBacklinkIndex(vault, OWNER_B);
  expect((scoped.get(TARGET) ?? []).map((r) => r.source)).toEqual(["pref-also-shared"]);

  // The owner still sees its own, and an absent scope still sees both -
  // the nine existing call sites pass nothing and are unaffected.
  const asOwner = buildBacklinkIndex(vault, OWNER_A);
  expect((asOwner.get(TARGET) ?? []).map((r) => r.source).toSorted()).toEqual([
    "pref-also-shared",
    "pref-owned-by-a",
  ]);
});

test("a legacy-frontmatter preference is reported, not silently dropped", () => {
  writePref("shared", null, "the target");
  writeLegacyPref("legacy", `points at [[${TARGET}]]`);

  const index = buildBacklinkIndex(vault);
  // The ref is still absent - the fields could not be read - but the
  // caller is now told which artifact was skipped and why, so a `count`
  // of 0 beside a non-empty report is distinguishable from a real zero.
  expect(index.get(TARGET)).toBeUndefined();
  expect(index.unparsed.map((u) => u.source)).toEqual(["pref-legacy"]);
  expect(index.unparsed[0]!.sourceKind).toBe("preference");
  expect(index.unparsed[0]!.reason).toContain("'_status'");
  // The reason crosses the MCP boundary: no absolute host path in it.
  expect(index.unparsed[0]!.reason).not.toContain(vault);
});

test("a clean vault reports no failures at all", () => {
  writePref("shared", null, "the target");
  writePref("other", null, `points at [[${TARGET}]]`);
  expect(buildBacklinkIndex(vault).unparsed).toEqual([]);
});

test("another owner's unparseable artifact is withheld from the failure report", () => {
  // Reporting it would name the artifact the ref filter just withheld,
  // which is the leak with the evidence moved one field over. The
  // artifact's owner is still readable from its frontmatter - it is the
  // DERIVED keys that fail - so the ownership rule still has a subject.
  writePref("shared", null, "the target");
  const legacy = join(brainDirs(vault).preferences, "pref-legacy.md");
  writeLegacyPref("legacy", `points at [[${TARGET}]]`);
  writeFileSync(
    legacy,
    readFileSync(legacy, "utf8").replace(
      "kind: brain-preference",
      `kind: brain-preference\nowner: ${OWNER_A}`,
    ),
  );

  expect(buildBacklinkIndex(vault).unparsed.map((u) => u.source)).toEqual(["pref-legacy"]);
  expect(buildBacklinkIndex(vault, OWNER_B).unparsed).toEqual([]);
  expect(buildBacklinkIndex(vault, OWNER_A).unparsed.map((u) => u.source)).toEqual(["pref-legacy"]);
});