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
/**
* Post-creation expiration mutation (unit 3c / t_5e338af1).
*
* The defect, both halves of it. `expiration_date` had a validator, a
* writer parameter on both artifact kinds, and a fully-wired read side -
* and no surface anywhere that set it. A memory's lifetime could
* therefore be declared only by a caller writing straight to the core
* API, and could never be changed at all: nothing in the tree rewrites
* that field after the write. `brain_update_note` cannot reach a
* preference (its path envelope refuses the `Brain/` root, and that
* refusal is load-bearing), so the mutation needs a surface of its own.
*
* Claims pinned here:
*
* 1. Setting an expiration on a signal or a preference stamps the
* NORMALISED value and leaves every other frontmatter field intact.
* 2. Changing an existing expiration replaces it; clearing removes the
* key entirely rather than writing an empty string.
* 3. Every value goes through `normalizeExpirationDate`, so an
* unparseable date is refused by name and the file is untouched.
* 4. An id that names no artifact is refused by name - never a silent
* no-op that reads as success.
* 5. An artifact mutated to expire drops out of the DEFAULT query after
* its date and comes back under `showExpired`, which is the whole
* point of setting one.
* 6. `changed: false` means what it says: the stored value is compared
* through the same chokepoint the incoming one goes through, so an
* equivalent spelling writes no bytes and logs no event.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { regenerateActive } from "../../../src/core/brain/active.ts";
import {
EXPIRATION_CLEAR,
ExpirationTargetNotFoundError,
ExpirationValueError,
setExpiration,
} from "../../../src/core/brain/expiration-set.ts";
import { queryByRuleTopic } from "../../../src/core/brain/query.ts";
import { resolveAppendShardId } from "../../../src/core/brain/ledger-shards.ts";
import { logShardJsonlPath } from "../../../src/core/brain/paths.ts";
import { writePreference } from "../../../src/core/brain/preference.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
let vault: string;
let configHome: string;
let configPath: string;
const CREATED = "2026-06-01T00:00:00Z";
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-expiration-set-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-expiration-set-cfg-"));
configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
/** Frontmatter lines of a page, minus the one field under test. */
function frontmatterLines(text: string): string[] {
return text
.split("\n---")[0]!
.split("\n")
.filter((l) => l.length > 0 && !l.startsWith("expiration_date:"));
}
/** Every byte of the observation log, so a no-op can be shown to append none. */
function logSnapshot(): string {
const dir = join(vault, "Brain", "log");
if (!existsSync(dir)) return "";
return readdirSync(dir)
.toSorted()
.map((name) => `${name}\n${readFileSync(join(dir, name), "utf8")}`)
.join("");
}
function seedSignal(): string {
return writeSignal(vault, {
topic: "staging-endpoint",
signal: "positive",
agent: "tester",
principle: "Use the staging endpoint.",
created_at: CREATED,
date: "2026-06-01",
slug: "staging-endpoint",
scope: "coding",
}).id;
}
function seedPreference(): string {
return writePreference(
vault,
{
slug: "staging-endpoint",
topic: "staging-endpoint",
principle: "Use the staging endpoint.",
created_at: CREATED,
unconfirmed_until: CREATED,
confirmed_at: CREATED,
status: "confirmed",
evidenced_by: [],
scope: "coding",
},
{ configPath },
).id;
}
describe("setting an expiration", () => {
test("updates the digest if the expiration saves but the audit append fails", () => {
const id = seedPreference();
const now = new Date("2026-07-16T12:00:00Z");
const digest = regenerateActive(vault, { now }).path;
expect(readFileSync(digest, "utf8")).toContain(id);
const logPath = logShardJsonlPath(vault, "2026-07-16", resolveAppendShardId());
mkdirSync(logPath, { recursive: true });
expect(() => setExpiration(vault, id, "2026-07-15", { now })).toThrow("EISDIR");
const page = join(vault, "Brain", "preferences", `${id}.md`);
expect(readFileSync(page, "utf8")).toContain("expiration_date: 2026-07-15");
expect(readFileSync(digest, "utf8")).not.toContain(id);
});
test("the digest drops expired preferences and restores them when expiration is cleared", () => {
const id = seedPreference();
const now = new Date("2026-07-16T12:00:00Z");
const digest = regenerateActive(vault, { now }).path;
expect(readFileSync(digest, "utf8")).toContain(id);
setExpiration(vault, id, "2026-07-15", { now });
expect(readFileSync(digest, "utf8")).toContain("## Confirmed (0)");
expect(readFileSync(digest, "utf8")).not.toContain(id);
expect(existsSync(join(vault, "Brain", "preferences", `${id}.md`))).toBe(true);
setExpiration(vault, id, EXPIRATION_CLEAR, { now });
expect(readFileSync(digest, "utf8")).toContain("## Confirmed (1)");
expect(readFileSync(digest, "utf8")).toContain(id);
});
test("stamps a signal and leaves its other frontmatter alone", () => {
const id = seedSignal();
const before = readFileSync(join(vault, "Brain/inbox", `${id}.md`), "utf8");
const res = setExpiration(vault, id, "2026-07-15");
expect(res.id).toBe(id);
expect(res.expiration).toBe("2026-07-15");
expect(res.previous).toBeNull();
const after = readFileSync(join(vault, res.path), "utf8");
expect(after).toContain("expiration_date: 2026-07-15");
// Every other field survives: compare the frontmatter line sets minus
// the one this call is allowed to add.
expect(frontmatterLines(after)).toEqual(frontmatterLines(before));
});
test("stamps a preference the same way", () => {
const id = seedPreference();
const res = setExpiration(vault, id, "2026-07-15");
expect(res.path).toBe(`Brain/preferences/${id}.md`);
expect(readFileSync(join(vault, res.path), "utf8")).toContain("expiration_date: 2026-07-15");
});
test("normalises the value rather than storing it verbatim", () => {
const id = seedSignal();
const res = setExpiration(vault, id, " 2026-07-15 ");
expect(res.expiration).toBe("2026-07-15");
});
});
describe("changing and clearing", () => {
test("a second set replaces the date and reports the previous one", () => {
const id = seedSignal();
setExpiration(vault, id, "2026-07-15");
const res = setExpiration(vault, id, "2026-09-01");
expect(res.previous).toBe("2026-07-15");
expect(res.expiration).toBe("2026-09-01");
expect(readFileSync(join(vault, res.path), "utf8")).not.toContain("2026-07-15");
});
test("clearing removes the key rather than writing an empty value", () => {
const id = seedSignal();
setExpiration(vault, id, "2026-07-15");
const res = setExpiration(vault, id, EXPIRATION_CLEAR);
expect(res.expiration).toBeNull();
expect(res.previous).toBe("2026-07-15");
const after = readFileSync(join(vault, res.path), "utf8");
expect(after).not.toContain("expiration_date");
});
test("re-setting the same lifetime writes nothing and logs nothing", () => {
const id = seedSignal();
const first = setExpiration(vault, id, "2026-07-15");
expect(first.changed).toBe(true);
// The two spellings of one lifetime: what is on disk carries padding
// - a hand edit, or a writer that quoted the scalar - and the caller
// sends the plain date. Comparing the raw stored value against the
// normalised new one made this a rewrite plus an audit event
// describing a change that did not happen.
const file = join(vault, first.path);
atomicWriteFileSync(
file,
readFileSync(file, "utf8").replace(
"expiration_date: 2026-07-15",
'expiration_date: "2026-07-15 "',
),
);
const bytesBefore = readFileSync(file, "utf8");
const logBefore = logSnapshot();
const res = setExpiration(vault, id, " 2026-07-15 ");
expect(res.changed).toBe(false);
expect(res.expiration).toBe("2026-07-15");
expect(readFileSync(file, "utf8")).toBe(bytesBefore);
expect(logSnapshot()).toBe(logBefore);
});
test("a stored value the validator cannot parse is never equal, so the set repairs it", () => {
const id = seedSignal();
const first = setExpiration(vault, id, "2026-07-15");
const file = join(vault, first.path);
atomicWriteFileSync(
file,
readFileSync(file, "utf8").replace("expiration_date: 2026-07-15", "expiration_date: junk"),
);
const res = setExpiration(vault, id, "2026-07-15");
expect(res.changed).toBe(true);
expect(readFileSync(file, "utf8")).toContain("expiration_date: 2026-07-15");
});
test("clearing an artifact that has none is reported, not invented", () => {
const id = seedSignal();
const res = setExpiration(vault, id, EXPIRATION_CLEAR);
expect(res.expiration).toBeNull();
expect(res.previous).toBeNull();
expect(res.changed).toBe(false);
});
});
describe("refusals", () => {
test("an unparseable date is refused by name and writes nothing", () => {
const id = seedSignal();
const before = readFileSync(join(vault, "Brain/inbox", `${id}.md`), "utf8");
expect(() => setExpiration(vault, id, "next tuesday")).toThrow(ExpirationValueError);
expect(readFileSync(join(vault, "Brain/inbox", `${id}.md`), "utf8")).toBe(before);
});
test("an impossible calendar date is refused too", () => {
const id = seedSignal();
expect(() => setExpiration(vault, id, "2026-13-40")).toThrow(ExpirationValueError);
});
test("an id naming no artifact is refused rather than silently succeeding", () => {
expect(() => setExpiration(vault, "pref-nobody-home", "2026-07-15")).toThrow(
ExpirationTargetNotFoundError,
);
});
});
describe("what an expiration is FOR", () => {
test("a mutated artifact drops out of the default query after its date", () => {
const signalId = seedSignal();
seedPreference();
setExpiration(vault, signalId, "2026-07-15");
const live = queryByRuleTopic(vault, "staging-endpoint", {
now: new Date("2026-07-15T12:00:00Z"),
});
expect(live.signals.map((s) => s.id)).toContain(signalId);
const lapsed = queryByRuleTopic(vault, "staging-endpoint", {
now: new Date("2026-07-16T00:00:01Z"),
});
expect(lapsed.signals.map((s) => s.id)).not.toContain(signalId);
const audited = queryByRuleTopic(vault, "staging-endpoint", {
now: new Date("2026-07-16T00:00:01Z"),
showExpired: true,
});
expect(audited.signals.map((s) => s.id)).toContain(signalId);
});
test("clearing puts it back in the default query", () => {
const signalId = seedSignal();
setExpiration(vault, signalId, "2026-07-15");
setExpiration(vault, signalId, EXPIRATION_CLEAR);
const after = queryByRuleTopic(vault, "staging-endpoint", {
now: new Date("2027-01-01T00:00:00Z"),
});
expect(after.signals.map((s) => s.id)).toContain(signalId);
});
});