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
7.5 KB
Raw Blame
/**
 * Language-agnostic co-occurrence auto-relate (Recall & Working-Memory
 * Quality Suite, t_7a632707).
 *
 * Entities that are repeatedly co-referenced from the same notes get a
 * suggested relationship edge, scored by a structural PMI/document-
 * frequency metric over the wikilink graph. The derivation reads only
 * link structure - no natural-language word list in any language - so a
 * vault written in a non-Latin script produces structurally identical
 * scores. Suggestions never mutate notes; they persist to a versioned,
 * hashed artifact that re-validates on read and fails soft.
 */

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

import {
  CO_OCCURRENCE_SCHEMA_VERSION,
  computeCoOccurrenceSuggestions,
  readCoOccurrenceSuggestions,
  writeCoOccurrenceSuggestions,
} from "../../../../src/core/brain/link-graph/co-occurrence.ts";

let vault: string;

function writeNote(rel: string, body: string): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, body, "utf8");
}

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-cooccurrence-"));
  // An unswitched vault: its Brain/ tree is the legacy layout under test.
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

describe("computeCoOccurrenceSuggestions", () => {
  test("two notes co-referencing the same pair yield one suggestion", () => {
    writeNote("notes/m1.md", "# M1\n\nSee [[alpha]] and [[beta]].\n");
    writeNote("notes/m2.md", "# M2\n\nAlso [[alpha]] with [[beta]] again.\n");
    // An unrelated note enlarges the document universe so the alpha/beta
    // co-occurrence is more than chance (PMI > 0).
    writeNote("notes/m3.md", "# M3\n\nDifferent [[gamma]] and [[delta]].\n");
    writeNote("notes/alpha.md", "# Alpha\n\nStandalone.\n");
    writeNote("notes/beta.md", "# Beta\n\nStandalone.\n");
    const result = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });
    const pair = result.suggestions.find((s) => s.left === "alpha" && s.right === "beta");
    expect(pair).toBeDefined();
    expect(pair!.coDocumentCount).toBe(2);
    expect(pair!.score).toBeGreaterThan(0);
  });

  test("a pair co-referenced only once is below the min-co-document floor", () => {
    writeNote("notes/m1.md", "# M1\n\nSee [[alpha]] and [[beta]].\n");
    const result = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });
    expect(result.suggestions.some((s) => s.left === "alpha" && s.right === "beta")).toBe(false);
  });

  test("an already directly-linked pair is not re-suggested", () => {
    // alpha links beta directly, so a co-reference must not re-propose them.
    writeNote("notes/m1.md", "# M1\n\nSee [[alpha]] and [[beta]].\n");
    writeNote("notes/alpha.md", "# Alpha\n\nLinks [[beta]] directly.\n");
    writeNote("notes/beta.md", "# Beta\n\nStandalone.\n");
    const result = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 1 });
    expect(result.suggestions.some((s) => s.left === "alpha" && s.right === "beta")).toBe(false);
  });

  test("scores are language-agnostic: a non-Latin vault scores identically", () => {
    writeNote("notes/m1.md", "# M1\n\nSee [[alpha]] and [[beta]].\n");
    writeNote("notes/m2.md", "# M2\n\nAlso [[alpha]] with [[beta]].\n");
    writeNote("notes/m3.md", "# M3\n\nDifferent [[gamma]] and [[delta]].\n");
    const latin = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });

    rmSync(vault, { recursive: true, force: true });
    vault = mkdtempSync(join(tmpdir(), "o2b-cooccurrence-cjk-"));
    // An unswitched vault: its Brain/ tree is the legacy layout under test.
    mkdirSync(join(vault, "Brain"), { recursive: true });
    writeNote("notes/m1.md", "# M1\n\nSee [[行列]] and [[共鳴]].\n");
    writeNote("notes/m2.md", "# M2\n\nAlso [[行列]] with [[共鳴]].\n");
    writeNote("notes/m3.md", "# M3\n\nDifferent [[勾配]] and [[時系列]].\n");
    const cjk = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });

    expect(latin.suggestions[0]!.score).toBeGreaterThan(0);
    expect(cjk.suggestions).toHaveLength(latin.suggestions.length);
    expect(cjk.suggestions[0]!.coDocumentCount).toBe(latin.suggestions[0]!.coDocumentCount);
    expect(cjk.suggestions[0]!.score).toBe(latin.suggestions[0]!.score);
  });

  test("is deterministic: identical vault yields identical suggestions and order", () => {
    writeNote("notes/m1.md", "# M1\n\n[[a]] [[b]] [[c]]\n");
    writeNote("notes/m2.md", "# M2\n\n[[a]] [[b]] [[c]]\n");
    const first = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });
    const second = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });
    expect(JSON.stringify(first.suggestions)).toBe(JSON.stringify(second.suggestions));
  });

  test("multi-word entity names round-trip through the pair key intact", () => {
    // Canonical keys keep internal spaces; the pair key/split must not
    // corrupt them (regression: a single-space separator split at the first
    // space and mangled multi-word titles).
    writeNote("notes/m1.md", "# M1\n\nSee [[Project Alpha]] and [[Meeting Notes]].\n");
    writeNote("notes/m2.md", "# M2\n\nAlso [[Project Alpha]] with [[Meeting Notes]].\n");
    writeNote("notes/m3.md", "# M3\n\nDifferent [[gamma]] and [[delta]].\n");
    const result = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });
    const pair = result.suggestions.find(
      (s) => s.left === "meeting notes" && s.right === "project alpha",
    );
    expect(pair).toBeDefined();
    expect(pair!.coDocumentCount).toBe(2);
  });

  test("the limit caps the number of suggestions", () => {
    writeNote("notes/m1.md", "# M1\n\n[[a]] [[b]] [[c]] [[d]]\n");
    writeNote("notes/m2.md", "# M2\n\n[[a]] [[b]] [[c]] [[d]]\n");
    const result = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2, limit: 2 });
    expect(result.suggestions.length).toBeLessThanOrEqual(2);
  });
});

describe("persistence", () => {
  test("write then read round-trips the suggestions", () => {
    writeNote("notes/m1.md", "# M1\n\n[[alpha]] [[beta]]\n");
    writeNote("notes/m2.md", "# M2\n\n[[alpha]] [[beta]]\n");
    const result = computeCoOccurrenceSuggestions(vault, { minCoDocuments: 2 });
    writeCoOccurrenceSuggestions(vault, result, { generatedAt: "2026-06-14T00:00:00.000Z" });
    const reloaded = readCoOccurrenceSuggestions(vault);
    expect(reloaded).not.toBeNull();
    expect(reloaded!.schema).toBe(CO_OCCURRENCE_SCHEMA_VERSION);
    expect(JSON.stringify(reloaded!.suggestions)).toBe(JSON.stringify(result.suggestions));
  });

  test("a missing artifact reads as null (fail-soft)", () => {
    expect(readCoOccurrenceSuggestions(vault)).toBeNull();
  });

  test("a corrupt artifact reads as null (fail-soft)", () => {
    mkdirSync(join(vault, "Brain", "link-graph"), { recursive: true });
    writeFileSync(join(vault, "Brain", "link-graph", "co-occurrence.json"), "{not json", "utf8");
    expect(readCoOccurrenceSuggestions(vault)).toBeNull();
  });

  test("a drifted schema version reads as null", () => {
    mkdirSync(join(vault, "Brain", "link-graph"), { recursive: true });
    writeFileSync(
      join(vault, "Brain", "link-graph", "co-occurrence.json"),
      JSON.stringify({ schema: "o2b.cooccurrence.v999", suggestions: [] }),
      "utf8",
    );
    expect(readCoOccurrenceSuggestions(vault)).toBeNull();
  });
});