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
/**
* Task 3: `buildActivityTimeline(index, opts)` merged chronological
* activity timeline renderer.
*
* Fixtures are built through the real `buildTimelineIndex` over a tmp
* vault with `Brain/log/<date>.jsonl` day files (same pattern as
* `build-index.test.ts` / `select-events.test.ts`), so the merge order
* and tie-break rules this module relies on are pinned against the
* actual index builder rather than a hand-rolled stand-in.
*
* One exception: the empty-age-label rendering branch requires an
* event whose `at` is not a parseable timestamp, and `buildTimelineIndex`
* only ever emits events with a disk-validated ISO timestamp (the JSONL
* reader rejects any other shape). Hand-crafting a `TimelineIndex`
* literal through the public `TemporalEvent` / `TimelineIndex` shapes is
* the only way to exercise that branch, so that one test builds its
* fixture directly instead of through disk.
*/
import { describe, expect, test, beforeEach } from "bun:test";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { buildActivityTimeline } from "../../../../src/core/brain/temporal/activity-timeline.ts";
import { buildTimelineIndex } from "../../../../src/core/brain/temporal/build-index.ts";
import type { TemporalEvent, TimelineIndex } from "../../../../src/core/brain/temporal/types.ts";
import { tempDirs } from "../../../helpers/temp-dir.ts";
const mkTemp = tempDirs();
function makeVault(): string {
const dir = mkTemp("o2b-activity-timeline-");
mkdirSync(join(dir, "Brain", "log"), { recursive: true });
mkdirSync(join(dir, "Brain", "preferences"), { recursive: true });
mkdirSync(join(dir, "Brain", "retired"), { recursive: true });
return dir;
}
interface FixtureEvent {
readonly timestamp: string;
readonly kind: string;
readonly body: Record<string, string | ReadonlyArray<string>>;
}
function writeJsonlDay(vault: string, date: string, events: ReadonlyArray<FixtureEvent>): void {
const lines = events
.map((e) => JSON.stringify({ ts: e.timestamp, kind: e.kind, payload: e.body }))
.join("\n");
writeFileSync(join(vault, "Brain", "log", `${date}.jsonl`), lines + "\n");
}
let VAULT: string;
beforeEach(() => {
VAULT = makeVault();
});
describe("buildActivityTimeline - merge order and tie-break", () => {
test("merges events across kinds newest-first, matching buildTimelineIndex's chronological order reversed", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T08:00:00Z", kind: "note", body: { text: "morning note" } },
]);
writeJsonlDay(VAULT, "2026-05-21", [
{
timestamp: "2026-05-21T09:00:00Z",
kind: "feedback",
body: { signal: "[[sig-2026-05-21-foo]]", topic: "foo" },
},
]);
writeJsonlDay(VAULT, "2026-05-22", [
{
timestamp: "2026-05-22T10:00:00Z",
kind: "apply-evidence",
body: { preference: "[[pref-bar|Bar]]", artifact: "[[a.ts]]", result: "applied" },
},
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-23T00:00:00Z") });
expect(tl.entries.map((e) => e.kind)).toEqual(["apply-evidence", "feedback", "note"]);
expect(tl.entries.map((e) => e.at)).toEqual([
"2026-05-22T10:00:00Z",
"2026-05-21T09:00:00Z",
"2026-05-20T08:00:00Z",
]);
});
test("tie-break stability: same timestamp across kinds keeps compareEvents's source.path order, reversed", () => {
// Two events at the identical instant land in the same day file at
// different line offsets; buildTimelineIndex's compareEvents breaks
// the `at` tie by source.path then source.line (both events share
// the same file, so line order decides). Ascending index order is
// [line 1, line 2]; buildActivityTimeline must reverse that to
// [line 2, line 1] for its newest-first contract.
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T08:00:00Z", kind: "note", body: { text: "first-in-file" } },
{ timestamp: "2026-05-20T08:00:00Z", kind: "note", body: { text: "second-in-file" } },
]);
const idx = buildTimelineIndex(VAULT, {});
// Pin the premise: the index itself is ascending oldest-first with
// this tie-break, so the renderer's reversal is the only thing
// under test here.
expect(idx.events.map((e) => e.text)).toEqual(["first-in-file", "second-in-file"]);
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T09:00:00Z") });
expect(tl.entries.map((e) => e.text)).toEqual(["second-in-file", "first-in-file"]);
});
test("does not mutate the index's events array", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T08:00:00Z", kind: "note", body: { text: "a" } },
{ timestamp: "2026-05-20T09:00:00Z", kind: "note", body: { text: "b" } },
]);
const idx = buildTimelineIndex(VAULT, {});
const before = idx.events.map((e) => e.text);
buildActivityTimeline(idx, { now: new Date("2026-05-21T00:00:00Z") });
expect(idx.events.map((e) => e.text)).toEqual(before);
expect(Object.isFrozen(idx.events)).toBe(true);
});
});
describe("buildActivityTimeline - limit and total", () => {
beforeEach(() => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T08:00:00Z", kind: "note", body: { text: "one" } },
{ timestamp: "2026-05-20T09:00:00Z", kind: "note", body: { text: "two" } },
{ timestamp: "2026-05-20T10:00:00Z", kind: "note", body: { text: "three" } },
{ timestamp: "2026-05-20T11:00:00Z", kind: "note", body: { text: "four" } },
{ timestamp: "2026-05-20T12:00:00Z", kind: "note", body: { text: "five" } },
]);
});
test("no limit returns every windowed event with total matching entry count", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-21T00:00:00Z") });
expect(tl.entries.length).toBe(5);
expect(tl.total).toBe(5);
});
test("limit truncates the newest-first list; total keeps the full windowed count", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-21T00:00:00Z"), limit: 2 });
expect(tl.entries.map((e) => e.text)).toEqual(["five", "four"]);
expect(tl.total).toBe(5);
});
test("limit larger than the windowed count returns everything with no error", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-21T00:00:00Z"), limit: 100 });
expect(tl.entries.length).toBe(5);
expect(tl.total).toBe(5);
});
test("limit 0 returns zero entries but preserves the total count", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-21T00:00:00Z"), limit: 0 });
expect(tl.entries.length).toBe(0);
expect(tl.bullets.length).toBe(0);
expect(tl.total).toBe(5);
});
test("negative limit is a fail-closed rejection, not a silent fallback", () => {
const idx = buildTimelineIndex(VAULT, {});
expect(() =>
buildActivityTimeline(idx, { now: new Date("2026-05-21T00:00:00Z"), limit: -1 }),
).toThrow();
});
test("non-integer limit is a fail-closed rejection", () => {
const idx = buildTimelineIndex(VAULT, {});
expect(() =>
buildActivityTimeline(idx, { now: new Date("2026-05-21T00:00:00Z"), limit: 1.5 }),
).toThrow();
});
});
describe("buildActivityTimeline - window filtering", () => {
beforeEach(() => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T00:00:00Z", kind: "note", body: { text: "lower-boundary" } },
{ timestamp: "2026-05-20T12:00:00Z", kind: "note", body: { text: "inside" } },
]);
writeJsonlDay(VAULT, "2026-05-21", [
{ timestamp: "2026-05-21T00:00:00Z", kind: "note", body: { text: "upper-boundary" } },
]);
});
test("since is inclusive and until is exclusive, matching selectEvents's own contract", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, {
now: new Date("2026-05-22T00:00:00Z"),
since: "2026-05-20T00:00:00Z",
until: "2026-05-21T00:00:00Z",
});
// lower-boundary included (since inclusive), upper-boundary excluded
// (until exclusive); newest-first order.
expect(tl.entries.map((e) => e.text)).toEqual(["inside", "lower-boundary"]);
expect(tl.total).toBe(2);
});
test("since alone narrows the lower bound only", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, {
now: new Date("2026-05-22T00:00:00Z"),
since: "2026-05-20T12:00:00Z",
});
expect(tl.entries.map((e) => e.text)).toEqual(["upper-boundary", "inside"]);
});
test("until alone narrows the upper bound only", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, {
now: new Date("2026-05-22T00:00:00Z"),
until: "2026-05-20T12:00:00Z",
});
expect(tl.entries.map((e) => e.text)).toEqual(["lower-boundary"]);
});
});
describe("buildActivityTimeline - bullet rendering and age labels", () => {
test("bullet shape is `- [<kind>] <text> - <age>` with the age separated by a middle dot", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T00:00:00Z", kind: "note", body: { text: "shipped v1" } },
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T00:05:00Z") });
expect(tl.bullets).toEqual(["- [note] shipped v1 · 5m ago"]);
expect(tl.text).toBe("- [note] shipped v1 · 5m ago");
});
test("omits the age suffix entirely when relativeAge returns empty (unparseable timestamp)", () => {
// relativeAge only returns "" for an unparseable `at`, and
// buildTimelineIndex's JSONL reader validates every `at` it emits
// against a strict ISO regex - so this branch cannot be reached
// through a disk fixture. Hand-craft a minimal TimelineIndex
// through the public TemporalEvent/TimelineIndex shapes instead.
const ev: TemporalEvent = Object.freeze({
at: "not-a-real-timestamp",
kind: "note",
source: Object.freeze({ path: "Brain/log/2026-05-20.jsonl", line: 1 }),
text: "garbled clock event",
});
const idx: TimelineIndex = Object.freeze({
events: Object.freeze([ev]),
eventsByKind: new Map([["note", Object.freeze([ev])]]) as TimelineIndex["eventsByKind"],
eventsByPrefId: new Map() as TimelineIndex["eventsByPrefId"],
eventsByTopic: new Map() as TimelineIndex["eventsByTopic"],
window: Object.freeze({ since: "1970-01-01T00:00:00Z", until: "2999-01-01T00:00:00Z" }),
});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T00:05:00Z") });
expect(tl.entries.length).toBe(1);
expect(tl.entries[0]!.ageLabel).toBe("");
expect(tl.bullets).toEqual(["- [note] garbled clock event"]);
});
test("joined text concatenates bullets with newlines", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T00:00:00Z", kind: "note", body: { text: "first" } },
{ timestamp: "2026-05-20T01:00:00Z", kind: "note", body: { text: "second" } },
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T02:00:00Z") });
expect(tl.text).toBe(tl.bullets.join("\n"));
expect(tl.text.split("\n").length).toBe(2);
});
});
describe("buildActivityTimeline - structural per-kind text derivation", () => {
test("note events use the text field verbatim", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T00:00:00Z", kind: "note", body: { text: "Release v1 shipped" } },
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T01:00:00Z") });
expect(tl.entries[0]!.text).toBe("Release v1 shipped");
});
test("apply-evidence events derive from pref id plus result, in that order", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{
timestamp: "2026-05-20T00:00:00Z",
kind: "apply-evidence",
body: { preference: "[[pref-foo|Principle]]", artifact: "[[a.ts]]", result: "applied" },
},
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T01:00:00Z") });
expect(tl.entries[0]!.text).toBe("pref=pref-foo result=applied artifact=a.ts");
});
test("reconcile events with a topic derive from the topic field", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{
timestamp: "2026-05-20T00:00:00Z",
kind: "reconcile",
body: { topic: "release-cadence", domain: "claims", reason: "no auto-resolution" },
},
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T01:00:00Z") });
expect(tl.entries[0]!.text).toBe("topic=release-cadence reason=no auto-resolution");
});
test("an event with no usable field falls back to kind plus its source pointer", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{
timestamp: "2026-05-20T00:00:00Z",
kind: "scan-inline",
body: { scanned: "3", created: "1", deduped: "0", malformed: "0" },
},
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T01:00:00Z") });
expect(tl.entries[0]!.text).toBe("scan-inline (Brain/log/2026-05-20.jsonl:1)");
});
});
describe("buildActivityTimeline - determinism and framing", () => {
test("two calls with identical inputs produce identical output", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T00:00:00Z", kind: "note", body: { text: "a" } },
{ timestamp: "2026-05-20T01:00:00Z", kind: "feedback", body: { topic: "b" } },
]);
const idx = buildTimelineIndex(VAULT, {});
const now = new Date("2026-05-20T02:00:00Z");
const first = buildActivityTimeline(idx, { now });
const second = buildActivityTimeline(idx, { now });
expect(first).toEqual(second);
});
test("envelope and its arrays are frozen", () => {
writeJsonlDay(VAULT, "2026-05-20", [
{ timestamp: "2026-05-20T00:00:00Z", kind: "note", body: { text: "a" } },
]);
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T01:00:00Z") });
expect(Object.isFrozen(tl)).toBe(true);
expect(Object.isFrozen(tl.entries)).toBe(true);
expect(Object.isFrozen(tl.entries[0])).toBe(true);
expect(Object.isFrozen(tl.bullets)).toBe(true);
});
test("empty index returns a frozen empty envelope", () => {
const idx = buildTimelineIndex(VAULT, {});
const tl = buildActivityTimeline(idx, { now: new Date("2026-05-20T01:00:00Z") });
expect(tl.entries.length).toBe(0);
expect(tl.bullets.length).toBe(0);
expect(tl.text).toBe("");
expect(tl.total).toBe(0);
});
});