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
9.9 KB
Raw Blame
/**
 * Session-entity mining inside the import loop (recall-quality, B1).
 *
 * Mining runs where the raw turn text still exists - recall rows may
 * hold externalized payload placeholders, but the import loop reads the
 * transcript line before anything is externalized. The lane writes ONE
 * continuity record per (family, key, session), honors the capture
 * boundary (an ignored file imports nothing, a stateless scan writes
 * nothing), withholds turns carrying a `<private>` region whole, refuses
 * secret-shaped tokens, and reports every outcome through never-silent
 * counters on the import result.
 */

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

import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import {
  continuityLogDir,
  listContinuityRecords,
} from "../../../../src/core/brain/continuity/store.ts";
import {
  MAX_MINED_KEYS_PER_SESSION,
  SESSION_ENTITY_MENTION_KIND,
} from "../../../../src/core/brain/link-graph/session-mining.ts";
import { importSession } from "../../../../src/core/brain/sessions/import.ts";
import { brainConfigPath } from "../../../../src/core/brain/paths.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
import { FAKE_VENDOR_KEY, fakeCredential } from "../../../helpers/fake-credentials.ts";

let tmp: string;
let vault: string;
let sessionsDir: string;

const NOW = new Date("2026-09-18T10:00:00Z");

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-import-mining-"));
  vault = join(tmp, "vault");
  sessionsDir = mkdtempSync(join(tmpdir(), "o2b-import-mining-sessions-"));
  bootstrapBrain(vault);
});

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

/** One Claude-format session file, each text a USER turn. */
function writeUserSession(name: string, texts: readonly string[]): string {
  return writeSession(
    name,
    texts.map((text) => ({ role: "user" as const, text })),
  );
}

/** One Claude-format session file with alternating user/assistant turns. */
function writeSession(
  name: string,
  turns: ReadonlyArray<{ readonly role: "user" | "assistant"; readonly text: string }>,
): string {
  const lines = turns.map((turn, i) =>
    JSON.stringify({
      type: turn.role,
      parentUuid: null,
      entrypoint: "cli",
      sessionId: "s1",
      uuid: `u-${i}`,
      timestamp: "2026-09-18T09:00:00.000Z",
      message: { role: turn.role, content: [{ type: "text", text: turn.text }] },
    }),
  );
  const path = join(sessionsDir, name);
  writeFileSync(path, lines.join("\n") + "\n", "utf8");
  return path;
}

function ledgerMentions(): ReturnType<typeof listContinuityRecords> {
  return listContinuityRecords(vault, { kind: SESSION_ENTITY_MENTION_KIND });
}

function setSessionsPolicy(lines: string[]): void {
  const path = brainConfigPath(vault);
  atomicWriteFileSync(path, readFileSync(path, "utf8") + "\n" + lines.join("\n") + "\n");
}

describe("importSession - session entity mining", () => {
  test("an admitted turn mints one mention per (family, key, session)", async () => {
    const path = writeUserSession("mining-basic.jsonl", [
      "wire `SessionStore` to https://osb.example/run today",
    ]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(result.mined_extracted).toBe(2);
    expect(result.mined_deduped).toBe(0);
    const records = ledgerMentions();
    expect(records.length).toBe(2);
    const keys = records.map((r) => `${r.payload["family"]}:${r.payload["key"]}`).toSorted();
    expect(keys).toEqual(["symbol:SessionStore", "url:https://osb.example/run"]);
    // Provenance keys on the portable session identity, never a host path.
    for (const record of records) {
      expect(record.payload["session_ref"]).toBe("mining-basic.jsonl");
      expect(record.sourceRefs[0]!.id.startsWith("mining-basic.jsonl:")).toBe(true);
    }
  });

  test("assistant turns are mined too, and the per-session fold dedupes repeats", async () => {
    const path = writeSession("mining-dedupe.jsonl", [
      { role: "user", text: "touch `SessionStore` please" },
      { role: "assistant", text: "edited SessionStore via `SessionStore` just now" },
    ]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    // Turn 1 mints symbol:SessionStore; turn 2 repeats it - the prose
    // "SessionStore" is not code and mines nothing, the code span dedupes.
    expect(result.mined_extracted).toBe(1);
    expect(result.mined_deduped).toBe(1);
    expect(ledgerMentions().length).toBe(1);
  });

  test("a dry run forecasts the mined count and writes nothing", async () => {
    const path = writeUserSession("mining-dry.jsonl", ["pin `SessionStore` here"]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW, dryRun: true });

    expect(result.mined_extracted).toBe(0);
    expect(result.mined_withheld).toBe(1);
    expect(ledgerMentions()).toEqual([]);
  });

  test("secret-shaped tokens are refused and counted, never written", async () => {
    const tok = fakeCredential("tok", "en-9f8e7d6c5b");
    const path = writeUserSession("mining-secrets.jsonl", [
      `key \`${FAKE_VENDOR_KEY}\` and https://osb.example/pull?token=${tok}`,
    ]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(result.mined_extracted).toBe(0);
    expect(result.mined_secret_refused).toBe(2);
    expect(ledgerMentions()).toEqual([]);
  });

  test("a turn carrying a private region is withheld from mining whole", async () => {
    const path = writeUserSession("mining-private.jsonl", [
      "public plan: use `PublicStore` here",
      "private notes: <private>token `SecretStore` inside</private>",
    ]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(result.mined_private_withheld).toBe(1);
    expect(result.mined_extracted).toBe(1);
    const records = ledgerMentions();
    expect(records.length).toBe(1);
    expect(records[0]!.payload["key"]).toBe("PublicStore");
  });

  test("a file matching an ignore glob mines nothing and still reports counters", async () => {
    setSessionsPolicy(["sessions:", "  ignore_patterns:", '    - "*cron-export*"']);
    const path = writeUserSession("cron-export-1.jsonl", ["wire `SessionStore` here"]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(result.boundary_decision).toBe("ignore");
    expect(result.mined_extracted).toBe(0);
    expect(result.mined_deduped).toBe(0);
    expect(result.mined_withheld).toBe(0);
    expect(result.mined_secret_refused).toBe(0);
    expect(result.mined_private_withheld).toBe(0);
    expect(result.mined_ledger_failed).toBe(0);
    expect(result.mined_cap_overflow).toBe(0);
    expect(ledgerMentions()).toEqual([]);
  });

  test("a stateless scan stays read-only: no mentions are written", async () => {
    setSessionsPolicy(["sessions:", "  stateless_patterns:", '    - "*scratch*"']);
    const path = writeUserSession("scratch-notes.jsonl", ["wire `SessionStore` here"]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(result.boundary_decision).toBe("stateless");
    expect(result.mined_extracted).toBe(0);
    expect(ledgerMentions()).toEqual([]);
  });

  test("re-importing the session appends no duplicate mention rows", async () => {
    const path = writeUserSession("mining-reimport.jsonl", ["pin `SessionStore` here"]);
    await importSession(vault, path, { agent: "tester", now: NOW });
    // A run's dedupe set is seeded from the ledger rows already on disk,
    // so a re-import folds every mention to its (family, key, sessionRef)
    // row instead of appending a duplicate: the ledger stays one row per
    // mention no matter how often the directory import repeats.
    const second = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(second.mined_extracted).toBe(0);
    expect(second.mined_deduped).toBe(1);
    expect(ledgerMentions().length).toBe(1);

    const third = await importSession(vault, path, { agent: "tester", now: NOW });
    expect(third.mined_extracted).toBe(0);
    expect(third.mined_deduped).toBe(1);
    expect(ledgerMentions().length).toBe(1);
  });

  test("a sabotaged ledger mid-import names the failure through the import result", async () => {
    // Sabotage: a regular file where the continuity ledger's directory must
    // be, so every mention append throws. The import itself still succeeds
    // (telemetry-grade tolerance), but the result's counters must say so -
    // the miner's ledgerFailed slot surfaced, never swallowed between the
    // miner and the import report.
    writeFileSync(continuityLogDir(vault), "not a directory\n");
    const path = writeUserSession("mining-ledger-fail.jsonl", ["pin `SessionStore` here"]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(result.mined_extracted).toBe(0);
    expect(result.mined_ledger_failed).toBe(1);
    expect(result.errors).toEqual([]);
    // Repair the read side, then confirm nothing landed while it was down.
    rmSync(continuityLogDir(vault), { force: true });
    expect(ledgerMentions()).toEqual([]);
  });

  test("an over-cap session reports the overflow through the import result", async () => {
    const overCap = MAX_MINED_KEYS_PER_SESSION + 3;
    const text = Array.from({ length: overCap }, (_, i) => `\`Import_cap_key_${i}\``).join("\n");
    const path = writeUserSession("mining-cap.jsonl", [text]);

    const result = await importSession(vault, path, { agent: "tester", now: NOW });

    expect(result.mined_extracted).toBe(MAX_MINED_KEYS_PER_SESSION);
    expect(result.mined_cap_overflow).toBe(3);
    expect(result.mined_ledger_failed).toBe(0);
    expect(ledgerMentions().length).toBe(MAX_MINED_KEYS_PER_SESSION);
  });
});