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
/**
* Anticipatory Brain context cache
* (continuity-hygiene-freshness suite, Task 6; kanban t_4cee9df5).
*
* The cache keeps a small, inspectable, turn-specific context pack
* warm while an agent works: refreshed from existing hook events (no
* daemon, no watcher), debounced by TTL with an injected clock, written
* atomically, keyed by the lineage root. Reads return the warm cache
* or fall back to a live pack, always reporting `cache_state`.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { tmpdir } from "node:os";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { captureSessionLifecycleEvent } from "../../../src/core/brain/session-lifecycle.ts";
import { recordLineageObservation } from "../../../src/core/brain/lineage/ledger.ts";
import {
ANTICIPATORY_SCHEMA_VERSION,
anticipatoryCachePath,
readAnticipatoryContext,
refreshAnticipatoryCache,
} from "../../../src/core/brain/anticipatory-cache.ts";
import { PACK_STAMP_FIELD } from "../../../src/core/brain/pack-stamp.ts";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-anticipatory-"));
bootstrapBrain(vault);
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
const T0 = new Date("2026-06-10T12:00:00Z");
describe("refreshAnticipatoryCache", () => {
test("writes a cache keyed by the lineage root", () => {
recordLineageObservation(vault, {
sessionId: "child-1",
at: T0.toISOString(),
event: "SessionStart",
lineage: { rootId: "root-1", parentId: "root-1", depth: 1, source: "payload" },
});
const result = refreshAnticipatoryCache(vault, {
sessionId: "child-1",
signalText: "debugging the indexer",
now: T0,
});
expect(result.refreshed).toBe(true);
expect(result.rootSessionId).toBe("root-1");
const raw = JSON.parse(readFileSync(anticipatoryCachePath(vault, "root-1"), "utf8")) as {
schema: string;
root_session_id: string;
};
// A literal, not the constant: comparing the constant to itself is a
// tautology that can never catch an unintended schema-token change.
expect(raw.schema).toBe("o2b.anticipatory.v2");
expect(ANTICIPATORY_SCHEMA_VERSION).toBe("o2b.anticipatory.v2");
expect(raw.root_session_id).toBe("root-1");
});
test("debounces by TTL with the injected clock", () => {
const first = refreshAnticipatoryCache(vault, { sessionId: "s-1", now: T0 });
expect(first.refreshed).toBe(true);
const second = refreshAnticipatoryCache(vault, {
sessionId: "s-1",
now: new Date(T0.getTime() + 30_000),
ttlSeconds: 120,
});
expect(second.refreshed).toBe(false);
const third = refreshAnticipatoryCache(vault, {
sessionId: "s-1",
now: new Date(T0.getTime() + 121_000),
ttlSeconds: 120,
});
expect(third.refreshed).toBe(true);
});
test("distinct roots that sanitize identically never share a cache file", () => {
const pathA = anticipatoryCachePath(vault, "a/b");
const pathB = anticipatoryCachePath(vault, "a:b");
expect(pathA).not.toBe(pathB);
const longA = anticipatoryCachePath(vault, "x".repeat(150) + "A");
const longB = anticipatoryCachePath(vault, "x".repeat(150) + "B");
expect(longA).not.toBe(longB);
});
test("a token-budget change bypasses the TTL debounce and is never served warm", () => {
refreshAnticipatoryCache(vault, { sessionId: "s-budget", now: T0, maxTokens: 2000 });
const rebuilt = refreshAnticipatoryCache(vault, {
sessionId: "s-budget",
now: new Date(T0.getTime() + 5_000),
maxTokens: 500,
});
expect(rebuilt.refreshed).toBe(true);
const read = readAnticipatoryContext(vault, {
sessionId: "s-budget",
now: new Date(T0.getTime() + 10_000),
maxTokens: 4000,
});
expect(read.cache_state).not.toBe("warm");
});
test("sanitizes hostile session ids into safe cache filenames", () => {
const result = refreshAnticipatoryCache(vault, { sessionId: "../../etc/passwd", now: T0 });
expect(result.refreshed).toBe(true);
const path = anticipatoryCachePath(vault, "../../etc/passwd");
expect(path).toContain(join("Brain", ".state", "anticipatory"));
expect(path.includes("..")).toBe(false);
});
});
describe("readAnticipatoryContext", () => {
test("returns the warm cache inside the TTL", () => {
refreshAnticipatoryCache(vault, { sessionId: "s-2", signalText: "warm topic", now: T0 });
const read = readAnticipatoryContext(vault, {
sessionId: "s-2",
now: new Date(T0.getTime() + 10_000),
ttlSeconds: 120,
});
expect(read.cache_state).toBe("warm");
expect(read.generated_at).toBe(T0.toISOString());
expect(Array.isArray(read.context.items)).toBe(true);
});
test("falls back to a live pack on miss", () => {
const read = readAnticipatoryContext(vault, { sessionId: "never-cached", now: T0 });
expect(read.cache_state).toBe("miss");
expect(Array.isArray(read.context.items)).toBe(true);
});
test("falls back to a live pack when the cache is stale", () => {
refreshAnticipatoryCache(vault, { sessionId: "s-3", now: T0 });
const read = readAnticipatoryContext(vault, {
sessionId: "s-3",
now: new Date(T0.getTime() + 10 * 60_000),
ttlSeconds: 120,
});
expect(read.cache_state).toBe("stale");
});
test("treats a corrupt cache file as a miss instead of throwing", () => {
const path = anticipatoryCachePath(vault, "s-4");
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, "not-json", "utf8");
const read = readAnticipatoryContext(vault, { sessionId: "s-4", now: T0 });
expect(read.cache_state).toBe("miss");
});
});
describe("provenance stamp and validity window", () => {
function writePref(slug: string, body: string, mtimeSeconds: number): void {
const path = join(vault, "Brain", "preferences", `pref-${slug}.md`);
mkdirSync(dirname(path), { recursive: true });
writeFileSync(
path,
[
"---",
`id: pref-${slug}`,
`topic: ${slug}`,
"principle: p",
"tier: core",
"---",
"",
body,
].join("\n"),
);
utimesSync(path, mtimeSeconds, mtimeSeconds);
}
test("the cache records the pack's stamp", () => {
writePref("stamped", "a body", 1_700_000_000);
refreshAnticipatoryCache(vault, { sessionId: "s-stamp", now: T0 });
const raw = JSON.parse(readFileSync(anticipatoryCachePath(vault, "s-stamp"), "utf8")) as Record<
string,
unknown
>;
const stamp = raw["stamp"] as { tokens: Record<string, string | null>; expires_at: string };
expect(typeof stamp.tokens[PACK_STAMP_FIELD.brainTree]).toBe("string");
expect(typeof stamp.expires_at).toBe("string");
});
test("editing a Brain note invalidates a warm cache entry and names the reason", () => {
writePref("edited", "original body", 1_700_000_000);
refreshAnticipatoryCache(vault, { sessionId: "s-edit", now: T0 });
expect(
readAnticipatoryContext(vault, { sessionId: "s-edit", now: new Date(T0.getTime() + 5_000) })
.cache_state,
).toBe("warm");
writePref("edited", "a rewritten body of a different length", 1_700_000_500);
const read = readAnticipatoryContext(vault, {
sessionId: "s-edit",
now: new Date(T0.getTime() + 6_000),
});
expect(read.cache_state).toBe("miss");
expect(read.cache_refusal).toBeDefined();
expect(read.cache_refusal!).toContain(PACK_STAMP_FIELD.brainTree);
});
test("a refused entry is served warm again once it is rebuilt", () => {
writePref("rebuilt", "original body", 1_700_000_000);
refreshAnticipatoryCache(vault, { sessionId: "s-rebuild", now: T0 });
writePref("rebuilt", "a rewritten body of a different length", 1_700_000_500);
const refused = readAnticipatoryContext(vault, {
sessionId: "s-rebuild",
now: new Date(T0.getTime() + 6_000),
});
expect(refused.cache_state).toBe("miss");
// The drifted entry must not survive the TTL debounce: a refresh
// inside the debounce window still rebuilds, because the stamp -
// not the clock - is the primary invalidator.
const refreshed = refreshAnticipatoryCache(vault, {
sessionId: "s-rebuild",
now: new Date(T0.getTime() + 7_000),
});
expect(refreshed.refreshed).toBe(true);
const read = readAnticipatoryContext(vault, {
sessionId: "s-rebuild",
now: new Date(T0.getTime() + 8_000),
});
expect(read.cache_state).toBe("warm");
expect(read.cache_refusal).toBeUndefined();
});
test("an expired validity window is refused rather than served, naming the expiry", () => {
writePref("expiring", "a body", 1_700_000_000);
writeFileSync(
join(vault, "Brain", "_brain.yaml"),
readFileSync(join(vault, "Brain", "_brain.yaml"), "utf8") +
"\nintegrity:\n pack_validity_seconds: 60\n",
);
refreshAnticipatoryCache(vault, { sessionId: "s-expire", now: T0, ttlSeconds: 3_600 });
const read = readAnticipatoryContext(vault, {
sessionId: "s-expire",
now: new Date(T0.getTime() + 61_000),
ttlSeconds: 3_600,
});
expect(read.cache_state).toBe("miss");
expect(read.cache_refusal).toBeDefined();
expect(read.cache_refusal!).toContain("2026-06-10T12:01:00.000Z");
});
test("a cache file written under the previous schema reads as a miss", () => {
const path = anticipatoryCachePath(vault, "s-legacy");
mkdirSync(dirname(path), { recursive: true });
writeFileSync(
path,
`${JSON.stringify(
{
schema: "o2b.anticipatory.v1",
root_session_id: "s-legacy",
session_id: "s-legacy",
generated_at: T0.toISOString(),
max_tokens: 2_000,
context: { items: [], session_hits: [] },
},
null,
2,
)}\n`,
"utf8",
);
const read = readAnticipatoryContext(vault, { sessionId: "s-legacy", now: T0 });
expect(read.cache_state).toBe("miss");
});
test("a cache file with no stamp at all reads as a miss, never as an unstamped hit", () => {
const path = anticipatoryCachePath(vault, "s-unstamped");
mkdirSync(dirname(path), { recursive: true });
writeFileSync(
path,
`${JSON.stringify(
{
schema: ANTICIPATORY_SCHEMA_VERSION,
root_session_id: "s-unstamped",
session_id: "s-unstamped",
generated_at: T0.toISOString(),
max_tokens: 2_000,
context: { items: [], session_hits: [] },
},
null,
2,
)}\n`,
"utf8",
);
const read = readAnticipatoryContext(vault, { sessionId: "s-unstamped", now: T0 });
expect(read.cache_state).toBe("miss");
});
});
describe("hook integration", () => {
test("a UserPromptSubmit lifecycle event warms the cache fail-soft", async () => {
await captureSessionLifecycleEvent(
vault,
{
hook_event_name: "UserPromptSubmit",
session_id: "hook-1",
cwd: "/work",
prompt: "plain prompt with no markers",
},
{ agent: "tester", now: T0 },
);
const read = readAnticipatoryContext(vault, { sessionId: "hook-1", now: T0 });
expect(read.cache_state).toBe("warm");
});
test("dry runs never write the cache", async () => {
await captureSessionLifecycleEvent(
vault,
{
hook_event_name: "UserPromptSubmit",
session_id: "hook-2",
cwd: "/work",
prompt: "plain prompt",
},
{ agent: "tester", now: T0, dryRun: true },
);
const read = readAnticipatoryContext(vault, { sessionId: "hook-2", now: T0 });
expect(read.cache_state).toBe("miss");
});
});
// ----- A4: the cache keys on the ENFORCED scope, not the requested one ----
describe("owner scope in the cache key", () => {
/**
* The two writers that warm the cache (the session-lifecycle hook and
* `o2b brain anticipate --refresh`) pass no scope; the MCP tool passes
* one unconditionally, because `coerceAgentScope(ctx, args, true)` falls
* back to `resolveAgentName`, which always returns a string. Keying the
* filename on the REQUESTED scope therefore made every MCP read a
* permanent miss on a default vault, rebuilding a full `packContext` on
* each call - an observable behaviour change with the gate off.
*/
test("a hook-warmed cache is warm for a scoped MCP read under the default gate", () => {
const warmed = refreshAnticipatoryCache(vault, { sessionId: "s-scope", now: T0 });
expect(warmed.refreshed).toBe(true);
const read = readAnticipatoryContext(vault, {
sessionId: "s-scope",
now: T0,
agentScope: "agent-a",
});
expect(read.cache_state).toBe("warm");
});
test("the hook-written path and the scoped read path are the same file", () => {
const hookPath = anticipatoryCachePath(vault, "root-1");
expect(anticipatoryCachePath(vault, "root-1", "agent-a")).toBe(hookPath);
expect(anticipatoryCachePath(vault, "root-1", "agent-b")).toBe(hookPath);
});
test("a second scoped read does not rebuild what the first one already had", () => {
refreshAnticipatoryCache(vault, { sessionId: "s-twice", now: T0 });
for (const scope of ["agent-a", "agent-b"]) {
expect(
readAnticipatoryContext(vault, { sessionId: "s-twice", now: T0, agentScope: scope })
.cache_state,
).toBe("warm");
}
});
});
/**
* Window-derived default budget (t_a567cc12, B4): when the operator
* declares a context window - the vault's `context:` block or the
* environment override - the default budget becomes a window fraction,
* floored at the historical 2_000, so it only ever scales UP. With
* nothing resolvable the 2_000 default stands byte-identically, and a
* budget the derivation decided is disclosed on the results that used it
* (`derivedMaxTokens` / `derived_max_tokens`); an explicit `maxTokens`
* input stays first-class and is never disclosed as derived.
*/
describe("window-derived default budget", () => {
const ENV_KEY = "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW";
let savedEnv: string | undefined;
function writeContextWindow(contents: string): void {
writeFileSync(join(vault, "Brain", "_brain.yaml"), contents);
}
function restoreEnv(): void {
if (savedEnv === undefined) delete process.env[ENV_KEY];
else process.env[ENV_KEY] = savedEnv;
savedEnv = undefined;
}
test("a declared window scales the default budget above the floor", () => {
writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 1000000\n");
const result = refreshAnticipatoryCache(vault, { sessionId: "s-win", now: T0 });
expect(result.refreshed).toBe(true);
expect(result.derivedMaxTokens).toBe(10_000);
const raw = JSON.parse(
readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),
) as { max_tokens: number };
expect(raw.max_tokens).toBe(10_000);
});
test("the floor keeps a small declared window at today's default", () => {
writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 100000\n");
const result = refreshAnticipatoryCache(vault, { sessionId: "s-floor", now: T0 });
// At the floor the derivation answered with the historical constant,
// so there is nothing derived to disclose and nothing observable
// changed.
expect(result.derivedMaxTokens).toBeUndefined();
const raw = JSON.parse(
readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),
) as { max_tokens: number };
expect(raw.max_tokens).toBe(2_000);
});
test("the environment override scales the budget", () => {
savedEnv = process.env[ENV_KEY];
process.env[ENV_KEY] = "500000";
try {
const result = refreshAnticipatoryCache(vault, { sessionId: "s-env", now: T0 });
expect(result.derivedMaxTokens).toBe(5_000);
} finally {
restoreEnv();
}
});
test("an explicit maxTokens wins and is not disclosed as derived", () => {
writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 1000000\n");
const result = refreshAnticipatoryCache(vault, {
sessionId: "s-explicit",
now: T0,
maxTokens: 500,
});
expect(result.derivedMaxTokens).toBeUndefined();
const raw = JSON.parse(
readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),
) as { max_tokens: number };
expect(raw.max_tokens).toBe(500);
});
test("nothing resolvable keeps the 2_000 default byte-identically", () => {
const result = refreshAnticipatoryCache(vault, { sessionId: "s-default", now: T0 });
expect(result.derivedMaxTokens).toBeUndefined();
const raw = JSON.parse(
readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),
) as { max_tokens: number };
expect(raw.max_tokens).toBe(2_000);
});
test("a broken _brain.yaml fails the derivation soft, and the refresh as always", () => {
writeContextWindow("schema_version: 1\ncontext:\n window_tokens: not-a-number\n");
const result = refreshAnticipatoryCache(vault, { sessionId: "s-broken", now: T0 });
// The derivation channel never answers for an unreadable config - no
// budget is disclosed - and the pack build raises on it exactly as it
// always has, so the fail-soft refresh reports a miss and writes
// nothing rather than caching a bundle under defaults the operator
// did not choose.
expect(result.refreshed).toBe(false);
expect(result.derivedMaxTokens).toBeUndefined();
});
test("the read path discloses the derived budget it answered under", () => {
writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 1000000\n");
refreshAnticipatoryCache(vault, { sessionId: "s-read", now: T0 });
const read = readAnticipatoryContext(vault, {
sessionId: "s-read",
now: new Date(T0.getTime() + 10_000),
ttlSeconds: 120,
});
expect(read.cache_state).toBe("warm");
expect(read.derived_max_tokens).toBe(10_000);
});
});