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; kanban t_4cee9df5).
*
* Prepare the next turn's memory evidence while the agent is still
* working, instead of waiting for an explicit search. Lifecycle hook
* events (prompt submit, tool use) refresh a small context bundle -
* the active context pack plus session-recall hits for the latest
* signal text - debounced by a TTL with an injected clock, written
* atomically under `Brain/.state/anticipatory/`, and keyed by the
* session's lineage root so one conversation keeps one cache across
* compression boundaries.
*
* Hard constraints honored here: NO daemon and NO file watcher
* (refresh piggybacks on events that already fire), and fail-soft
* everywhere - a broken cache is a miss, never an error that could
* block a hook.
*/
import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname } from "node:path";
import { resolveModelContextWindowEnvTokens } from "../config.ts";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import type { StampTokens } from "../integrity/stamp.ts";
import { pruneAnticipatoryCache } from "./anticipatory-prune.ts";
import { packContext, type ContextPackItem } from "./context-pack.ts";
import { resolveModelContextWindowTokens } from "./model-window.ts";
import { readLineageLedger } from "./lineage/ledger.ts";
import { packStampRefusal, packStampTokens, type ContextPackStamp } from "./pack-stamp.ts";
import { resolveOwnerScopeDelivery } from "./preferences-collect.ts";
import { resolveSessionLineage } from "./lineage/resolve.ts";
import { BRAIN_ANTICIPATORY_REL } from "./path-constants.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { searchSessionRecall, type SessionRecallHit } from "./session-recall.ts";
import { loadBrainConfig } from "./policy.ts";
import { machineStatePath } from "../state/machine-state.ts";
/**
* Cache-file schema token. Bumped to `v2` by context-integrity-gates
* (Unit B) because a `v1` file carries no provenance stamp: reusing the
* version would leave those entries readable as UNSTAMPED hits, which is
* exactly the "trusted forever" state the stamp exists to remove.
* `readCacheFile` already rejects a schema mismatch, so the bump needs no
* migration - every pre-existing file simply reads as a miss and is
* rebuilt on the next refresh.
*/
export const ANTICIPATORY_SCHEMA_VERSION = "o2b.anticipatory.v2";
/** Default debounce/freshness window. */
export const DEFAULT_ANTICIPATORY_TTL_SECONDS = 120;
/** Default token budget for the cached context pack. */
export const DEFAULT_ANTICIPATORY_MAX_TOKENS = 2_000;
/**
* The share of a resolved context window the default budget becomes when
* the window-fraction derivation fires (t_a567cc12, B4): 1/100th, so a
* declared 1M window budgets 10_000 and a 500k one 5_000. A divisor, not
* a float fraction, so the division is exact at every value the resolver
* can hand over (integers in [100_000, 1_000_000]).
*/
const ANTICIPATORY_WINDOW_BUDGET_DIVISOR = 100;
const DEFAULT_SESSION_HITS = 5;
export interface AnticipatoryContext {
readonly items: ReadonlyArray<ContextPackItem>;
readonly session_hits: ReadonlyArray<SessionRecallHit>;
}
export interface RefreshAnticipatoryCacheInput {
readonly sessionId: string;
/** Latest user-visible signal (prompt text) steering the bundle. */
readonly signalText?: string;
/** Injected clock - hooks pass their event time. */
readonly now: Date;
readonly ttlSeconds?: number;
readonly maxTokens?: number;
/**
* Owner scope for delivery isolation (context-integrity-gates, Unit
* A). Part of the cache IDENTITY, not just the pack build: a bundle
* assembled under one scope must never be served under another, which
* a path keyed only on the lineage root would allow between two agents
* sharing one conversation lineage.
*/
readonly agentScope?: string;
}
export interface RefreshAnticipatoryCacheResult {
readonly refreshed: boolean;
readonly rootSessionId: string;
readonly path: string;
/**
* The window-derived budget the refresh answered under (t_a567cc12,
* B4), present only when a resolved context window - the operator's
* `context:` block or the environment override - lifted the default
* above its historical 2_000 floor. Absent on an explicit-budget call
* and whenever nothing resolvable left the constant standing, so the
* default-vault result is byte-identical.
*/
readonly derivedMaxTokens?: number;
}
export type AnticipatoryCacheState = "warm" | "stale" | "miss";
export interface ReadAnticipatoryContextInput {
readonly sessionId: string;
readonly now: Date;
readonly ttlSeconds?: number;
readonly maxTokens?: number;
/**
* Owner scope for delivery isolation (context-integrity-gates, Unit
* A). Part of the cache IDENTITY, not just the pack build: a bundle
* assembled under one scope must never be served under another, which
* a path keyed only on the lineage root would allow between two agents
* sharing one conversation lineage.
*/
readonly agentScope?: string;
}
export interface ReadAnticipatoryContextResult {
readonly cache_state: AnticipatoryCacheState;
readonly root_session_id: string;
/** Stamp of the cache that answered (warm reads only). */
readonly generated_at?: string;
/**
* Why an otherwise-fresh cache entry was REFUSED rather than served
* (context-integrity-gates, Unit B): its provenance stamp drifted from
* the vault, or its validity window closed. Present only on a refusal,
* so an ordinary miss or a TTL-stale read stays byte-identical. The
* refusal is named rather than silent precisely so a stale bundle and
* a broken mechanism stay distinguishable.
*/
readonly cache_refusal?: string;
readonly context: AnticipatoryContext;
/**
* The window-derived budget this read answered under (t_a567cc12, B4),
* present only when a resolved context window lifted the default above
* its historical 2_000 floor - the read-side twin of
* `derivedMaxTokens`, so a consumer can tell a derived warm cache from
* a constant-budget one. Absent on an explicit-budget read and on the
* default-vault path.
*/
readonly derived_max_tokens?: number;
}
/** On-disk form of {@link ContextPackStamp} (snake_case, like its siblings). */
interface CacheStamp {
readonly tokens: Record<string, string | null>;
readonly generated_at: string;
readonly expires_at: string;
}
interface CacheFile {
readonly schema: string;
readonly root_session_id: string;
readonly session_id: string;
readonly generated_at: string;
/** Token budget the cached pack was built under (variant field). */
readonly max_tokens: number;
readonly signal?: string;
/** What the cached pack was derived from, and when it stops being servable. */
readonly stamp: CacheStamp;
readonly context: AnticipatoryContext;
}
function toCacheStamp(stamp: ContextPackStamp): CacheStamp {
return {
tokens: { ...stamp.tokens },
generated_at: stamp.generatedAt,
expires_at: stamp.expiresAt,
};
}
function fromCacheStamp(stamp: CacheStamp): ContextPackStamp {
return {
tokens: stamp.tokens as StampTokens,
generatedAt: stamp.generated_at,
expiresAt: stamp.expires_at,
};
}
/**
* Collision-resistant flat filename for any root id: a readable
* sanitized prefix plus a content digest, so distinct roots that
* sanitize identically (`a/b` vs `a:b`) or differ only past the
* prefix never share a cache file.
*/
function safeCacheKey(rootId: string): string {
const prefix = rootId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80) || "_";
const digest = createHash("sha256").update(rootId).digest("hex").slice(0, 16);
return `${prefix}-${digest}`;
}
/**
* Cache file for a lineage root under an owner scope.
*
* The scope is part of the KEY, not merely of the payload. The cache
* persists a context pack to disk, so a path keyed only on the lineage
* root would let one agent's refresh materialize its memories into the
* exact file another scope reads back - a disk-persisted leak that
* outlives the process that caused it.
*
* The key uses the ENFORCED scope, resolved here rather than by the
* caller, so no call site can key on a scope that does not actually
* narrow the payload. That distinction is load-bearing:
* `coerceAgentScope(ctx, args, true)` falls back to `resolveAgentName`,
* which ALWAYS returns a string (the literal `"agent"` when nothing is
* configured), so `brain_anticipatory_context` passes a scope on every
* call regardless of the gate - while the two writers that warm the
* cache (the session-lifecycle hook and `o2b brain anticipate --refresh`)
* pass none. Keying on the REQUESTED scope therefore made the MCP read a
* permanent miss on a default vault, rebuilding a full `packContext` on
* every call. Under `off` and `warn` the pack is not narrowed either, so
* one file is the correct answer as well as the pre-gate one; only `fail`
* splits the cache, which is exactly when the payloads genuinely differ.
*
* An absent or non-enforcing scope keeps the legacy filename
* byte-for-byte, so warm caches written before the gate existed are still
* found.
*/
export function anticipatoryCachePath(
vault: string,
rootSessionId: string,
agentScope?: string | null,
): string {
const scope = resolveOwnerScopeDelivery(vault, agentScope ?? undefined).enforcedScope;
const key = safeCacheKey(scope === null ? rootSessionId : `${rootSessionId}\u0000${scope}`);
return machineStatePath(vault, BRAIN_ANTICIPATORY_REL, `${key}.json`);
}
function resolveRootId(vault: string, sessionId: string): string {
try {
return resolveSessionLineage({ sessionId }, { ledger: readLineageLedger(vault) }).rootId;
} catch {
return sessionId;
}
}
function readCacheFile(path: string): CacheFile | null {
if (!existsSync(path)) return null;
try {
const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
if (parsed === null || typeof parsed !== "object") return null;
const cache = parsed as CacheFile;
if (cache.schema !== ANTICIPATORY_SCHEMA_VERSION) return null;
if (typeof cache.generated_at !== "string") return null;
if (typeof cache.max_tokens !== "number") return null;
if (cache.context === null || typeof cache.context !== "object") return null;
if (!Array.isArray(cache.context.items) || !Array.isArray(cache.context.session_hits)) {
return null;
}
// An entry that carries no readable stamp is a miss, never an
// unstamped hit: the whole point of the stamp is that a persisted
// pack is verified rather than trusted, and a file that cannot be
// verified has nothing to offer over rebuilding.
if (!isCacheStamp(cache.stamp)) return null;
return cache;
} catch {
return null; // corrupt cache reads as a miss by contract
}
}
function isCacheStamp(value: unknown): value is CacheStamp {
if (value === null || typeof value !== "object") return false;
const stamp = value as CacheStamp;
if (typeof stamp.generated_at !== "string" || typeof stamp.expires_at !== "string") return false;
return stamp.tokens !== null && typeof stamp.tokens === "object" && !Array.isArray(stamp.tokens);
}
interface BuildBundleInput {
readonly sessionId: string;
readonly signalText: string | undefined;
readonly maxTokens: number;
readonly agentScope: string | undefined;
/** Injected clock; the stamp's window is anchored to it. */
readonly now: Date;
/** Candidate filter handed to the pack (absolute paths); absent keeps every candidate. */
readonly visible?: (absPath: string) => boolean;
}
interface BuiltBundle {
readonly context: AnticipatoryContext;
readonly stamp: ContextPackStamp;
}
function buildBundle(vault: string, input: BuildBundleInput): BuiltBundle {
const pack = packContext(vault, {
maxTokens: input.maxTokens,
...(input.agentScope !== undefined ? { agentScope: input.agentScope } : {}),
...(input.visible !== undefined ? { visible: input.visible } : {}),
stamp: { now: input.now },
});
const signal = input.signalText?.trim() ?? "";
const hits =
signal.length > 0
? searchSessionRecall(vault, {
query: signal,
sessionId: input.sessionId,
limit: DEFAULT_SESSION_HITS,
}).hits
: Object.freeze([] as SessionRecallHit[]);
return {
context: Object.freeze({ items: pack.items, session_hits: hits }),
stamp: pack.stamp,
};
}
/**
* Why a cached entry must not be served, or `null` when it may be.
* Shared by the refresh debounce and the read so the two can never
* disagree about what "still valid" means - a warm-but-drifted entry
* that survived the debounce would be refused on every read and never
* rebuilt until its TTL lapsed.
*/
function cacheRefusal(vault: string, cached: CacheFile, now: Date): string | null {
return packStampRefusal(fromCacheStamp(cached.stamp), packStampTokens(vault), now);
}
/**
* The window-derived default budget (t_a567cc12, B4), or `undefined` when
* the historical constant stands.
*
* Fires only on the derivation path - an explicit `maxTokens` input never
* reads the vault or the environment, so the explicit path behaves
* byte-identically to before the resolver existed. When it fires, the
* operator's `context:` block and the environment override are resolved
* through the shared model-window resolver (config > env; no model id
* reaches this module, so the declared/suffix tiers have no channel
* here), and the budget becomes the window's {@link
* ANTICIPATORY_WINDOW_BUDGET_DIVISOR}th part, floored at
* {@link DEFAULT_ANTICIPATORY_MAX_TOKENS} so it only ever scales UP.
*
* `disclosed` is the derived budget only when it lifted above the
* historical constant: at the floor the derivation answered with exactly
* the value the constant would have, so there is nothing derived to
* disclose and nothing observable changed.
*
* Fail-soft on both channels, matching this module's contract: a broken
* `_brain.yaml` or a malformed env value leaves the derivation empty -
* the config raise happens later, where the pack builds, exactly as it
* always has, and this channel must not answer for the operator's config
* before the real reader does.
*/
interface DerivedWindowBudget {
readonly budget: number;
readonly disclosed: number | undefined;
}
function deriveWindowBudget(vault: string): DerivedWindowBudget | undefined {
let operatorWindow: number | undefined;
try {
operatorWindow = loadBrainConfig(vault).context?.window_tokens;
} catch {
operatorWindow = undefined;
}
let envWindow: number | undefined;
try {
envWindow = resolveModelContextWindowEnvTokens();
} catch {
envWindow = undefined;
}
if (operatorWindow === undefined && envWindow === undefined) return undefined;
const resolved = resolveModelContextWindowTokens({
...(operatorWindow !== undefined ? { operatorWindowTokens: operatorWindow } : {}),
...(envWindow !== undefined ? { envWindowTokens: envWindow } : {}),
});
const budget = Math.max(
DEFAULT_ANTICIPATORY_MAX_TOKENS,
Math.floor(resolved.windowTokens / ANTICIPATORY_WINDOW_BUDGET_DIVISOR),
);
return {
budget,
disclosed: budget === DEFAULT_ANTICIPATORY_MAX_TOKENS ? undefined : budget,
};
}
/**
* Refresh the cache for the session's lineage root unless a fresh copy
* already exists (TTL debounce).
*
* Fail-soft by design: every cache-building error is swallowed and
* reported as `refreshed: false`. The ONE exception is the vault-identity
* refusal, which is raised ahead of the try so it cannot be mistaken for
* an ordinary cache miss - the only caller (the session-lifecycle hook)
* already catches, so the hook still fails open, but it fails open
* WITHOUT having written the cache into the wrong store.
*/
export function refreshAnticipatoryCache(
vault: string,
input: RefreshAnticipatoryCacheInput,
): RefreshAnticipatoryCacheResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
const rootId = resolveRootId(vault, input.sessionId);
const path = anticipatoryCachePath(vault, rootId, input.agentScope);
const ttlMs = (input.ttlSeconds ?? DEFAULT_ANTICIPATORY_TTL_SECONDS) * 1_000;
const derived = input.maxTokens === undefined ? deriveWindowBudget(vault) : undefined;
const maxTokens = input.maxTokens ?? derived?.budget ?? DEFAULT_ANTICIPATORY_MAX_TOKENS;
const disclosure =
derived?.disclosed !== undefined ? { derivedMaxTokens: derived.disclosed } : {};
try {
const existing = readCacheFile(path);
// TTL debounce applies only to a cache built under the same token
// budget; a budget change always rebuilds. The signal text is
// deliberately NOT part of the cache identity - it changes every
// prompt, and invalidating on it would defeat the debounce that
// makes hook-driven refresh affordable.
//
// The stamp overrides the debounce (context-integrity-gates, Unit
// B): a drifted or expired entry rebuilds even inside the TTL,
// because the stamp - not the clock - is the primary invalidator.
// Without this the read side would refuse the same drifted entry on
// every turn and never get a replacement until the TTL lapsed.
if (existing !== null && existing.max_tokens === maxTokens) {
const age = input.now.getTime() - Date.parse(existing.generated_at);
if (
Number.isFinite(age) &&
age >= 0 &&
age < ttlMs &&
cacheRefusal(vault, existing, input.now) === null
) {
return Object.freeze({
refreshed: false,
rootSessionId: rootId,
path,
...disclosure,
});
}
}
const bundle = buildBundle(vault, {
sessionId: input.sessionId,
signalText: input.signalText,
maxTokens,
agentScope: input.agentScope,
now: input.now,
});
const signal = input.signalText?.trim();
const cache: CacheFile = {
schema: ANTICIPATORY_SCHEMA_VERSION,
root_session_id: rootId,
session_id: input.sessionId,
generated_at: input.now.toISOString(),
max_tokens: maxTokens,
...(signal !== undefined && signal.length > 0 ? { signal } : {}),
stamp: toCacheStamp(bundle.stamp),
context: bundle.context,
};
// The file's own parent: one resolution of the state root per write.
mkdirSync(dirname(path), { recursive: true });
atomicWriteFileSync(path, `${JSON.stringify(cache, null, 2)}\n`);
// Retention rides on the write, never on the read path: entries are
// one per session and nothing else deletes them (rate-limited inside).
pruneAnticipatoryCache(vault, { keep: path });
return Object.freeze({
refreshed: true,
rootSessionId: rootId,
path,
...disclosure,
});
} catch {
return Object.freeze({
refreshed: false,
rootSessionId: rootId,
path,
...disclosure,
});
}
}
/**
* Read the warm cache for the session's lineage root, falling back to
* a live bundle on miss or staleness.
*
* A corrupt cache file reads as a miss, so nothing about the CACHE can
* fail this call. The live fallback can: it builds a context pack, and
* an unreadable `_brain.yaml` raises out of that deliberately rather
* than serving a pack under guardrails the operator did not choose. Both
* callers report it - the CLI verb as `anticipate failed: …`, the MCP
* tool as its error envelope. This said "Never throws" until the
* absent-versus-broken config split gave the pack a raise; the promise
* was the stale half.
*/
export function readAnticipatoryContext(
vault: string,
input: ReadAnticipatoryContextInput,
): ReadAnticipatoryContextResult {
const rootId = resolveRootId(vault, input.sessionId);
const path = anticipatoryCachePath(vault, rootId, input.agentScope);
const ttlMs = (input.ttlSeconds ?? DEFAULT_ANTICIPATORY_TTL_SECONDS) * 1_000;
const derived = input.maxTokens === undefined ? deriveWindowBudget(vault) : undefined;
const requestedTokens = input.maxTokens ?? derived?.budget ?? DEFAULT_ANTICIPATORY_MAX_TOKENS;
const disclosure =
derived?.disclosed !== undefined ? { derived_max_tokens: derived.disclosed } : {};
const cached = readCacheFile(path);
if (cached !== null) {
const age = input.now.getTime() - Date.parse(cached.generated_at);
if (cached.max_tokens === requestedTokens && Number.isFinite(age) && age >= 0 && age < ttlMs) {
// Fresh by the clock is not the same as valid. The stamp decides
// whether the persisted bundle still describes this vault, and an
// expired window decides when a bundle stops being servable even
// if nothing observable drifted.
const refusal = cacheRefusal(vault, cached, input.now);
if (refusal === null) {
return Object.freeze({
cache_state: "warm" as const,
root_session_id: rootId,
generated_at: cached.generated_at,
context: cached.context,
...disclosure,
});
}
return Object.freeze({
cache_state: "miss" as const,
root_session_id: rootId,
cache_refusal: refusal,
context: buildBundle(vault, {
sessionId: input.sessionId,
signalText: cached.signal,
maxTokens: requestedTokens,
agentScope: input.agentScope,
now: input.now,
}).context,
...disclosure,
});
}
return Object.freeze({
cache_state: "stale" as const,
root_session_id: rootId,
context: buildBundle(vault, {
sessionId: input.sessionId,
signalText: cached.signal,
maxTokens: requestedTokens,
agentScope: input.agentScope,
now: input.now,
}).context,
...disclosure,
});
}
return Object.freeze({
cache_state: "miss" as const,
root_session_id: rootId,
context: buildBundle(vault, {
sessionId: input.sessionId,
signalText: undefined,
maxTokens: requestedTokens,
agentScope: input.agentScope,
now: input.now,
}).context,
...disclosure,
});
}
export interface BuildReaderAnticipatoryContextInput extends ReadAnticipatoryContextInput {
/** Latest user-visible signal steering the session hits, if any. */
readonly signalText?: string;
/** Candidate filter for one reader (absolute paths). */
readonly visible: (absPath: string) => boolean;
}
/**
* A live bundle built for one reader, outside the shared cache.
*
* The cache entry is keyed by lineage root and owner scope only, so it
* holds the bundle one particular reader was entitled to. A reader whose
* candidates are filtered must neither be served that entry (it may carry
* pages this reader cannot read) nor write its own filtered bundle over
* it (the operator would then be served a narrowed bundle). This path
* therefore never reads or writes the cache file and answers `miss`,
* which is what it is: no cached bundle answered the call.
*/
export function buildReaderAnticipatoryContext(
vault: string,
input: BuildReaderAnticipatoryContextInput,
): ReadAnticipatoryContextResult {
const rootId = resolveRootId(vault, input.sessionId);
const signal = input.signalText?.trim();
const derived = input.maxTokens === undefined ? deriveWindowBudget(vault) : undefined;
return Object.freeze({
cache_state: "miss" as const,
root_session_id: rootId,
context: buildBundle(vault, {
sessionId: input.sessionId,
signalText: signal !== undefined && signal.length > 0 ? signal : undefined,
maxTokens: input.maxTokens ?? derived?.budget ?? DEFAULT_ANTICIPATORY_MAX_TOKENS,
agentScope: input.agentScope,
now: input.now,
visible: input.visible,
}).context,
...(derived?.disclosed !== undefined ? { derived_max_tokens: derived.disclosed } : {}),
});
}