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
10.3 KB
Raw Blame
/**
 * Pure origin-join core for standing-instruction provenance (recall lane).
 *
 * `preference-provenance.ts` is a read-time join: it parses a signal's
 * `session_ref` into origin coordinates and resolves a preference's
 * `evidenced_by` wikilinks to those coordinates through an injected
 * lookup. Three producers write `session_ref` today, each with its own
 * shape:
 *
 *   - import-session: `<portable basename>#<turn id>` — the ref is
 *     composed at src/core/brain/sessions/import.ts:445 from the key
 *     `sessionRefIdentity` returns (the session file's basename, never
 *     a machine-local path);
 *   - capture lifecycle: `session:<id>#<event>` — composed by
 *     `sessionReference` at src/core/brain/session-lifecycle.ts:858;
 *     the fragment is a hook event NAME (UserPromptSubmit, Stop,
 *     SessionEnd), not an event id, so it resolves as SESSION-level
 *     provenance (kind `session`) and is labeled as such;
 *   - auto-extract: a bare session reference with no fragment —
 *     src/core/brain/extract-signals.ts:646 stores the caller's
 *     session id verbatim, so no turn is available.
 *
 * The never-guess rule under every case below: a ref whose shape no
 * producer emits yields NO provenance, never a best-effort reading.
 */

import { describe, expect, test } from "bun:test";
import { readFileSync } from "node:fs";

import {
  parseSessionRef,
  resolvePreferenceProvenance,
} from "../../../src/core/brain/preference-provenance.ts";
// The live writer half of the import-session ref: the portable session
// key is exactly what `sessionRefIdentity` returns.
import { sessionRefIdentity } from "../../../src/core/brain/sessions/import.ts";

describe("parseSessionRef: producer shapes", () => {
  test("an import-session ref splits into portable basename and turn id", () => {
    // Live writer shape: `${sessionKey}#${input.turnId}` where the key
    // is `sessionRefIdentity`'s portable basename.
    const key = sessionRefIdentity("/host/only/path/sessions/claude-2026-06-01.jsonl");
    expect(key).toBe("claude-2026-06-01.jsonl");
    const origin = parseSessionRef(`${key}#turn-user-1`);
    expect(origin).toEqual({
      sessionKey: "claude-2026-06-01.jsonl",
      fragment: "turn-user-1",
      kind: "turn",
    });
  });

  test("a capture-lifecycle ref resolves as session-level provenance, labeled as such", () => {
    // Live writer shape: `session:${payload.sessionId}#${payload.event}`.
    // The fragment is the hook event's NAME, not an event id, so every
    // prompt-sourced signal in a session shares the one coordinate: the
    // kind says session, never a turn claim.
    const origin = parseSessionRef("session:00000000-0000-0000-0000-000000000001#UserPromptSubmit");
    expect(origin).toEqual({
      sessionKey: "session:00000000-0000-0000-0000-000000000001",
      fragment: "UserPromptSubmit",
      kind: "session",
    });
  });

  test("the degenerate unknown-session capture ref keeps its verbatim key", () => {
    // session-lifecycle stamps `unknown` when the host payload carries
    // no session id; the shape is still a lifecycle ref.
    const origin = parseSessionRef("session:unknown#SessionEnd");
    expect(origin).toEqual({
      sessionKey: "session:unknown",
      fragment: "SessionEnd",
      kind: "session",
    });
  });

  test("a session-prefixed key that is neither lifecycle form yields no provenance", () => {
    // Import keys are verbatim basenames: a session file named with the
    // lifecycle scheme collides with it, and the ref alone cannot tell
    // the two apart. The join refuses the label instead of guessing one -
    // no provenance, never a wrong kind.
    expect(parseSessionRef("session:my-session.jsonl#turn-user-1")).toBeNull();
    expect(parseSessionRef("session:conv-01#UserPromptSubmit")).toBeNull();
  });

  test("an auto-extract ref carries no fragment and yields no provenance", () => {
    // Live writer shape: the bare caller session id, no `#`.
    expect(parseSessionRef("session:conv-01")).toBeNull();
  });

  test("any ref without a fragment yields no provenance", () => {
    expect(parseSessionRef("claude-minimal.jsonl")).toBeNull();
  });
});

describe("parseSessionRef: malformed shapes are refused, never guessed", () => {
  test("missing and blank refs yield no provenance", () => {
    expect(parseSessionRef("")).toBeNull();
    expect(parseSessionRef("   ")).toBeNull();
  });

  test("an empty key or an empty fragment yields no provenance", () => {
    expect(parseSessionRef("#turn-1")).toBeNull();
    expect(parseSessionRef("claude-minimal.jsonl#")).toBeNull();
    expect(parseSessionRef("session:#UserPromptSubmit")).toBeNull();
  });

  test("a second hash — a shape no producer emits — yields no provenance", () => {
    expect(parseSessionRef("claude-minimal.jsonl#turn-1#extra")).toBeNull();
    expect(parseSessionRef("session:conv-01#UserPromptSubmit#x")).toBeNull();
  });
});

describe("resolvePreferenceProvenance", () => {
  const LOOKUP: Record<string, string | undefined> = {
    "sig-2026-05-16-mocking": "claude-minimal.jsonl#turn-user-1",
    "sig-2026-05-17-lifecycle": "session:00000000-0000-0000-0000-000000000002#UserPromptSubmit",
    "sig-2026-05-18-bare": "session:conv-02",
    "sig-2026-05-19-dup": "claude-minimal.jsonl#turn-user-1",
  };
  const lookup = (signalId: string): string | undefined => LOOKUP[signalId];

  test("resolves both producer kinds in evidence order, earliest cited first", () => {
    const provenance = resolvePreferenceProvenance(
      {
        id: "pref-db-mocking",
        evidenced_by: ["[[sig-2026-05-16-mocking]]", "[[sig-2026-05-17-lifecycle]]"],
      },
      lookup,
    );
    expect(provenance).not.toBeNull();
    expect(provenance?.key).toBe("pref:pref-db-mocking");
    expect(provenance?.preferenceId).toBe("pref-db-mocking");
    expect(provenance?.origins).toEqual([
      { sessionKey: "claude-minimal.jsonl", fragment: "turn-user-1", kind: "turn" },
      {
        sessionKey: "session:00000000-0000-0000-0000-000000000002",
        fragment: "UserPromptSubmit",
        kind: "session",
      },
    ]);
    // The earliest cited origin leads: the preference's evidence order,
    // never re-sorted, and never a chronological claim.
    expect(provenance?.origins[0]).toEqual({
      sessionKey: "claude-minimal.jsonl",
      fragment: "turn-user-1",
      kind: "turn",
    });
  });

  test("evidence whose signal is unknown is skipped without leaving a hole", () => {
    const provenance = resolvePreferenceProvenance(
      {
        id: "pref-partial",
        evidenced_by: ["[[sig-missing]]", "[[sig-2026-05-16-mocking]]"],
      },
      lookup,
    );
    expect(provenance?.origins).toEqual([
      { sessionKey: "claude-minimal.jsonl", fragment: "turn-user-1", kind: "turn" },
    ]);
  });

  test("an existing signal without a session_ref contributes no origin", () => {
    const provenance = resolvePreferenceProvenance(
      { id: "pref-noref", evidenced_by: ["[[sig-no-session-ref]]"] },
      () => undefined,
    );
    expect(provenance).toBeNull();
  });

  test("evidence entries that are not exact wikilinks are never guessed at", () => {
    const provenance = resolvePreferenceProvenance(
      {
        id: "pref-loose",
        evidenced_by: [
          "sig-2026-05-16-mocking", // bare id, no brackets
          "see [[sig-2026-05-16-mocking]] in context", // embedded in prose
          "", // empty entry
          "[[sig-2026-05-16-mocking|alias]]", // alias form: not what writers emit
          "[[sig-2026-05-16-mocking]]", // the one exact form
        ],
      },
      lookup,
    );
    expect(provenance?.origins).toEqual([
      { sessionKey: "claude-minimal.jsonl", fragment: "turn-user-1", kind: "turn" },
    ]);
  });

  test("duplicate origins dedupe to their first position", () => {
    const provenance = resolvePreferenceProvenance(
      {
        id: "pref-dup",
        evidenced_by: [
          "[[sig-2026-05-16-mocking]]",
          "[[sig-2026-05-17-lifecycle]]",
          "[[sig-2026-05-19-dup]]", // resolves to the same ref as the first
        ],
      },
      lookup,
    );
    expect(provenance?.origins).toEqual([
      { sessionKey: "claude-minimal.jsonl", fragment: "turn-user-1", kind: "turn" },
      {
        sessionKey: "session:00000000-0000-0000-0000-000000000002",
        fragment: "UserPromptSubmit",
        kind: "session",
      },
    ]);
  });

  test("ordering follows the preference's own evidence order, never a re-sort", () => {
    const provenance = resolvePreferenceProvenance(
      {
        id: "pref-order",
        evidenced_by: ["[[sig-late-z]]", "[[sig-early-a]]"],
      },
      (signalId) => (signalId === "sig-late-z" ? "zeta.jsonl#t9" : "alpha.jsonl#t1"),
    );
    expect(provenance?.origins).toEqual([
      { sessionKey: "zeta.jsonl", fragment: "t9", kind: "turn" },
      { sessionKey: "alpha.jsonl", fragment: "t1", kind: "turn" },
    ]);
  });

  test("a ref a producer cannot emit yields no provenance even through the lookup", () => {
    const provenance = resolvePreferenceProvenance(
      { id: "pref-weird", evidenced_by: ["[[sig-weird-ref]]"] },
      () => "not-even-wrong#k#v",
    );
    expect(provenance).toBeNull();
  });

  test("nothing resolves to null, not to an empty-hints value", () => {
    expect(
      resolvePreferenceProvenance({ id: "pref-none", evidenced_by: ["[[sig-missing]]"] }, lookup),
    ).toBeNull();
    expect(resolvePreferenceProvenance({ id: "pref-empty", evidenced_by: [] }, lookup)).toBeNull();
  });

  test("the join is deterministic across repeated calls", () => {
    const input = {
      id: "pref-det",
      evidenced_by: ["[[sig-2026-05-17-lifecycle]]", "[[sig-2026-05-16-mocking]]"],
    };
    const first = resolvePreferenceProvenance(input, lookup);
    const second = resolvePreferenceProvenance(input, lookup);
    expect(first).toEqual(second);
    expect(first?.origins[0]?.fragment).toBe("UserPromptSubmit");
  });
});

describe("purity pin", () => {
  test("the module is an import-free leaf: no fs, no path, no vault APIs", () => {
    const source = readFileSync(
      new URL("../../../src/core/brain/preference-provenance.ts", import.meta.url),
      "utf8",
    );
    expect(source).not.toMatch(/^[ \t]*import\b/m);
    expect(source).not.toMatch(/\brequire\s*\(/);
    expect(source).not.toContain("node:fs");
    expect(source).not.toContain("node:path");
    expect(source).not.toContain("vault");
  });
});