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
11.3 KB
Raw Blame
/**
 * Tests for `src/core/brain/lessons.ts` (t_62363378).
 *
 * Drives the unified, signed, recency-scored lessons corpus:
 *   - positive (apply-evidence `applied`) vs negative (`violated` /
 *     `outdated`, plus dead-end notes) outcomes folded into one score;
 *   - a signed, exponentially-decayed weight so a fresh dead-end
 *     outweighs a stale "useful";
 *   - a ≥N-distinct-results corroboration gate promoting `tentative`
 *     to `preferred`, with mixed-signal nodes rendered `contested`
 *     (recency-wins) and purely-negative nodes `avoid`.
 */

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

import {
  computeLessons,
  regenerateLessons,
  LESSON_TIER,
  LESSON_STANCE,
} from "../../../src/core/brain/lessons.ts";
import { appendLogEvent } from "../../../src/core/brain/log.ts";
import { recordDeadEnd } from "../../../src/core/brain/dead-ends.ts";
import type { BrainPreference } from "../../../src/core/brain/types.ts";
import {
  BRAIN_APPLY_RESULT,
  BRAIN_LOG_EVENT_KIND,
  BRAIN_PREFERENCE_STATUS,
} from "../../../src/core/brain/types.ts";
import type { DeadEndEntry } from "../../../src/core/brain/dead-ends.ts";

const NOW = new Date("2026-05-20T00:00:00Z");

function buildPref(id: string, overrides: Partial<BrainPreference> = {}): BrainPreference {
  const base: BrainPreference = {
    kind: "brain-preference",
    id,
    created_at: "2026-01-01T00:00:00Z",
    confirmed_at: null,
    unconfirmed_until: "2026-01-08T00:00:00Z",
    tags: [],
    topic: id.replace(/^pref-/, ""),
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    principle: `principle for ${id}`,
    evidenced_by: [],
    applied_count: 0,
    violated_count: 0,
    last_evidence_at: null,
    confidence: "medium",
    confidence_value: 0.5,
    pinned: false,
  };
  return { ...base, ...overrides };
}

function seed(
  vault: string,
  timestamp: string,
  prefWikilink: string,
  result: string,
  artifact = "[[src/foo.ts]]",
): void {
  appendLogEvent(vault, {
    timestamp,
    eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
    body: { preference: prefWikilink, artifact, agent: "tester", result },
  });
}

/** A lightweight dead-end entry (only the fields computeLessons reads). */
function deadEnd(id: string, approach: string, created_at: string): DeadEndEntry {
  return { id, path: `${id}.md`, approach, reason: "why", context: null, agent: "t", created_at };
}

describe("computeLessons", () => {
  let vault: string;
  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "osb-lessons-"));
    mkdirSync(join(vault, "Brain"), { recursive: true });
  });
  afterEach(() => {
    rmSync(vault, { recursive: true, force: true });
  });

  test("empty corpus yields no lessons", () => {
    expect(computeLessons(vault, [], [], { now: NOW })).toEqual([]);
  });

  test("a preference with no outcome evidence is not yet a lesson", () => {
    const result = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(result).toEqual([]);
  });

  test("two distinct applied artifacts promote to preferred", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    seed(vault, "2026-05-19T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[b.ts]]");
    const [lesson] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(lesson!.tier).toBe(LESSON_TIER.preferred);
    expect(lesson!.corroboration).toBe(2);
    expect(lesson!.signedScore).toBeGreaterThan(0);
  });

  test("a single applied artifact stays tentative (below corroboration floor)", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    seed(vault, "2026-05-19T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    const [lesson] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(lesson!.tier).toBe(LESSON_TIER.tentative);
    expect(lesson!.corroboration).toBe(1); // same artifact twice = one distinct result
  });

  test("corroborationMin option gates promotion", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    seed(vault, "2026-05-19T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[b.ts]]");
    const [strict] = computeLessons(vault, [buildPref("pref-a")], [], {
      now: NOW,
      corroborationMin: 3,
    });
    expect(strict!.tier).toBe(LESSON_TIER.tentative);
  });

  test("mixed applied + violated evidence renders contested", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.violated, "[[b.ts]]");
    const [lesson] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(lesson!.tier).toBe(LESSON_TIER.contested);
    expect(lesson!.stance).not.toBeNull();
  });

  test("contested stance follows recency: a fresh violation outweighs a stale applied", () => {
    // Stale positive (~4 months old), fresh negative (2 days old).
    seed(vault, "2026-01-20T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.violated, "[[b.ts]]");
    const [lesson] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(lesson!.tier).toBe(LESSON_TIER.contested);
    expect(lesson!.stance).toBe(LESSON_STANCE.negative);
    expect(lesson!.signedScore).toBeLessThan(0);
  });

  test("a rule only ever violated is avoid", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.violated, "[[a.ts]]");
    const [lesson] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(lesson!.tier).toBe(LESSON_TIER.avoid);
    expect(lesson!.signedScore).toBeLessThan(0);
  });

  test("dead-ends are avoid lessons with a negative score", () => {
    const de = deadEnd("de-2026-05-18-x", "tried the flaky retry loop", "2026-05-18T00:00:00Z");
    const [lesson] = computeLessons(vault, [], [de], { now: NOW });
    expect(lesson!.kind).toBe("dead-end");
    expect(lesson!.tier).toBe(LESSON_TIER.avoid);
    expect(lesson!.negativeMass).toBeGreaterThan(0);
    expect(lesson!.positiveMass).toBe(0);
    expect(lesson!.title).toBe("tried the flaky retry loop");
  });

  test("recency: a fresh dead-end outscores a stale preference in salience ranking", () => {
    // Stale applied preference (~4 months old) vs a 1-day-old dead-end.
    seed(vault, "2026-01-20T00:00:00Z", "[[pref-old]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    const de = deadEnd("de-2026-05-19-x", "fresh failed approach", "2026-05-19T00:00:00Z");
    const result = computeLessons(vault, [buildPref("pref-old")], [de], { now: NOW });
    // The fresh dead-end has larger decayed mass, so it ranks first.
    expect(result[0]!.id).toBe("de-2026-05-19-x");
  });

  test("outdated counts as a negative outcome", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.outdated, "[[a.ts]]");
    const [lesson] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(lesson!.tier).toBe(LESSON_TIER.avoid);
  });

  test("evidence predating the preference's created_at is ignored", () => {
    const pref = buildPref("pref-a", { created_at: "2026-05-01T00:00:00Z" });
    seed(vault, "2026-04-01T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    const result = computeLessons(vault, [pref], [], { now: NOW });
    expect(result).toEqual([]);
  });

  test("retired-status preferences are excluded from scoring", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    const pref = buildPref("pref-a", { status: "retired" as BrainPreference["status"] });
    expect(computeLessons(vault, [pref], [], { now: NOW })).toEqual([]);
  });

  test("wikilink aliases collapse to the bare id", () => {
    seed(
      vault,
      "2026-05-18T00:00:00Z",
      "[[pref-a|principle text]]",
      BRAIN_APPLY_RESULT.applied,
      "[[a.ts]]",
    );
    seed(
      vault,
      "2026-05-19T00:00:00Z",
      "[[pref-a|principle text]]",
      BRAIN_APPLY_RESULT.applied,
      "[[b.ts]]",
    );
    const [lesson] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(lesson!.tier).toBe(LESSON_TIER.preferred);
  });

  test("halfLifeDays option sharpens the decay", () => {
    // 30 days old applied event. A short half-life shrinks its weight.
    seed(vault, "2026-04-20T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    const [gentle] = computeLessons(vault, [buildPref("pref-a")], [], {
      now: NOW,
      halfLifeDays: 60,
    });
    const [sharp] = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW, halfLifeDays: 5 });
    expect(gentle!.signedScore).toBeGreaterThan(sharp!.signedScore);
  });

  test("limit truncates the ranked output", () => {
    const des = [
      deadEnd("de-1", "a", "2026-05-18T00:00:00Z"),
      deadEnd("de-2", "b", "2026-05-17T00:00:00Z"),
      deadEnd("de-3", "c", "2026-05-16T00:00:00Z"),
    ];
    const result = computeLessons(vault, [], des, { now: NOW, limit: 2 });
    expect(result.length).toBe(2);
  });

  test("output is deterministic and frozen", () => {
    seed(vault, "2026-05-18T00:00:00Z", "[[pref-a]]", BRAIN_APPLY_RESULT.applied, "[[a.ts]]");
    const first = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    const second = computeLessons(vault, [buildPref("pref-a")], [], { now: NOW });
    expect(first).toEqual(second);
    expect(Object.isFrozen(first)).toBe(true);
    expect(Object.isFrozen(first[0])).toBe(true);
  });
});

describe("regenerateLessons", () => {
  let vault: string;
  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "osb-lessons-regen-"));
    mkdirSync(join(vault, "Brain"), { recursive: true });
  });
  afterEach(() => {
    rmSync(vault, { recursive: true, force: true });
  });

  test("writes a lessons.md digest and reports counts", () => {
    recordDeadEnd(vault, {
      approach: "polling loop that never converges",
      reason: "burned the token budget",
      agent: "tester",
      now: new Date("2026-05-18T00:00:00Z"),
    });
    const result = regenerateLessons(vault, { now: NOW });
    expect(result.changed).toBe(true);
    expect(result.counts.avoid).toBe(1);
    expect(result.counts.total).toBe(1);

    const body = require("node:fs").readFileSync(result.path, "utf8") as string;
    expect(body).toContain("kind: brain-lessons");
    expect(body).toContain("## Avoid (1)");
    expect(body).toContain("polling loop that never converges");
  });

  test("idempotent: a second regeneration with the same clock does not rewrite", () => {
    recordDeadEnd(vault, {
      approach: "x",
      reason: "y",
      agent: "tester",
      now: new Date("2026-05-18T00:00:00Z"),
    });
    const first = regenerateLessons(vault, { now: NOW });
    expect(first.changed).toBe(true);
    const second = regenerateLessons(vault, { now: NOW });
    expect(second.changed).toBe(false);
  });

  test("empty corpus renders a placeholder body", () => {
    const result = regenerateLessons(vault, { now: NOW });
    expect(result.counts.total).toBe(0);
    const body = require("node:fs").readFileSync(result.path, "utf8") as string;
    expect(body).toContain("No lessons yet");
  });
});