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
/**
* Activation event store (Time-Aware Recall & Activation Suite,
* t_2bc79017 + t_c5ef25a3).
*
* Storage follows the `feedback.ts` convention exactly: one small JSON
* file per recorded access under `Brain/search/activation/` (the
* conflict-free one-file-per-signal pattern), and a derived
* `Brain/search/activation-state.json` that is a PURE FOLD over the
* retained events - deterministic, order-insensitive, replayable, and
* safe to delete.
*
* Sweep semantics are part of the activation model, not an
* afterthought: activation decays toward the type floor anyway, so
* dropping events older than the retention window (or beyond the
* newest-N cap) approximates the limit instead of corrupting it.
*
* Privacy: events carry an FNV-1a hash of the query, never raw text.
*
* A store-only machine (design D14 items 1 and 11) keeps both in its
* device-local state, never under the vault: the events record what this
* machine's searches surfaced and decay away, the state is their fold,
* and no other machine needs to agree on either, so they are not a store
* ledger.
*/
import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
import { dirname, join } from "node:path";
import { BRAIN_ROOT_REL } from "../../brain/path-constants.ts";
import { machineStatePath } from "../../state/machine-state.ts";
import { fnv1aHex } from "../feedback.ts";
import { bumpStrength } from "./decay.ts";
import type {
ActivationAccessEvent,
ActivationPathState,
ActivationState,
ActivationSweepOutcome,
CoAccessPair,
} from "./types.ts";
/** Cap on surfaced paths stored per access event. */
export const ACCESS_EVENT_PATHS_CAP = 10;
/** Default retention window for access events, in days. */
export const ACCESS_EVENT_RETENTION_DAYS = 90;
/** Default cap on retained access events. */
export const ACCESS_EVENT_MAX_COUNT = 5000;
/** Cap on co-access pairs kept in the derived state. */
export const CO_ACCESS_MAX_PAIRS = 500;
/** Pairs seen fewer times than this are noise and never boost. */
export const CO_ACCESS_MIN_COUNT = 2;
const DAY_MS = 24 * 60 * 60 * 1000;
export function activationDir(vault: string | null): string {
return join(activationRoot(vault), ACTIVATION_EVENTS_DIR);
}
export function activationStatePath(vault: string | null): string {
return join(activationRoot(vault), ACTIVATION_STATE_FILE);
}
const ACTIVATION_EVENTS_DIR = "activation";
const ACTIVATION_STATE_FILE = "activation-state.json";
/** The folder under `Brain/` that holds the activation files. */
const ACTIVATION_SEARCH_DIR = "search";
/**
* The folder both live in: `Brain/search/` on a legacy machine, else this
* machine's state for the vault (`state/machine-state.ts`): the switched
* machine's device-local folder, or one folder per bare vault, so two bare
* vaults on one machine never boost each other's paths.
*/
function activationRoot(vault: string | null): string {
return machineStatePath(vault, BRAIN_ROOT_REL, ACTIVATION_SEARCH_DIR);
}
/**
* Record one access event as its own file and refresh the derived
* state. The filename derives from the timestamp plus a content hash,
* so recording the identical event twice is idempotent.
*/
export function recordAccessEvent(vault: string | null, event: ActivationAccessEvent): string {
const dir = activationDir(vault);
mkdirSync(dir, { recursive: true });
const bounded: ActivationAccessEvent = {
ts: event.ts,
queryHash: event.queryHash,
paths: event.paths.slice(0, ACCESS_EVENT_PATHS_CAP),
};
const body = JSON.stringify(bounded, null, 2) + "\n";
const file = join(dir, `${bounded.ts}-${fnv1aHex(body)}.json`);
writeFileSync(file, body);
writeActivationState(vault, computeActivationState(loadAccessEvents(vault)));
return file;
}
/** Load all retained access events, sorted by ts then filename. */
export function loadAccessEvents(vault: string | null): ActivationAccessEvent[] {
const dir = activationDir(vault);
let files: string[];
try {
files = readdirSync(dir).filter((f) => f.endsWith(".json"));
} catch {
return [];
}
const out: ActivationAccessEvent[] = [];
for (const f of files.toSorted()) {
try {
const parsed = JSON.parse(readFileSync(join(dir, f), "utf8")) as ActivationAccessEvent;
const pathsValid =
Array.isArray(parsed.paths) && parsed.paths.every((p) => typeof p === "string");
if (
typeof parsed.ts === "number" &&
Number.isFinite(parsed.ts) &&
typeof parsed.queryHash === "string" &&
pathsValid
) {
out.push(parsed);
}
} catch {
// One malformed file never breaks the fold.
}
}
out.sort((a, b) => a.ts - b.ts);
return out;
}
/**
* The deterministic fold. Per path: strength is `bumpStrength` applied
* once per access (a pure function of the access COUNT, so the fold is
* order-insensitive by construction), `lastAccessAt` is the max ts.
* Co-access pairs count events that surfaced both paths together,
* bounded to the top {@link CO_ACCESS_MAX_PAIRS} by count then key.
*/
export function computeActivationState(
events: ReadonlyArray<ActivationAccessEvent>,
): ActivationState {
const counts = new Map<string, { count: number; lastAccessAt: number }>();
const pairCounts = new Map<string, number>();
let latestTs = 0;
for (const e of events) {
if (e.ts > latestTs) latestTs = e.ts;
const unique = Array.from(new Set(e.paths)).toSorted();
for (const p of unique) {
const row = counts.get(p) ?? { count: 0, lastAccessAt: 0 };
row.count++;
if (e.ts > row.lastAccessAt) row.lastAccessAt = e.ts;
counts.set(p, row);
}
for (let i = 0; i < unique.length; i++) {
for (let j = i + 1; j < unique.length; j++) {
const key = `${unique[i]}\n${unique[j]}`;
pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
}
}
}
const paths: Record<string, ActivationPathState> = {};
for (const p of Array.from(counts.keys()).toSorted()) {
const row = counts.get(p)!;
let strength = 0;
for (let i = 0; i < row.count; i++) strength = bumpStrength(strength);
paths[p] = Object.freeze({
strength: Math.round(strength * 1e6) / 1e6,
lastAccessAt: row.lastAccessAt,
accessCount: row.count,
});
}
const coAccess: CoAccessPair[] = Array.from(pairCounts.entries())
.map(([key, count]) => {
const [a, b] = key.split("\n") as [string, string];
return Object.freeze({ a, b, count });
})
.toSorted((x, y) => y.count - x.count || x.a.localeCompare(y.a) || x.b.localeCompare(y.b))
.slice(0, CO_ACCESS_MAX_PAIRS);
return Object.freeze({
version: 1,
events: events.length,
updatedAt: latestTs > 0 ? new Date(latestTs).toISOString() : null,
paths: Object.freeze(paths),
coAccess: Object.freeze(coAccess),
});
}
export function writeActivationState(vault: string | null, state: ActivationState): void {
const path = activationStatePath(vault);
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, JSON.stringify(state, null, 2) + "\n");
}
function isPathState(v: unknown): v is ActivationPathState {
if (v === null || typeof v !== "object") return false;
const row = v as Record<string, unknown>;
return (
typeof row["strength"] === "number" &&
Number.isFinite(row["strength"]) &&
typeof row["lastAccessAt"] === "number" &&
Number.isFinite(row["lastAccessAt"]) &&
typeof row["accessCount"] === "number" &&
Number.isInteger(row["accessCount"]) &&
(row["accessCount"] as number) >= 0
);
}
function isCoAccessPair(v: unknown): v is CoAccessPair {
if (v === null || typeof v !== "object") return false;
const p = v as Record<string, unknown>;
return (
typeof p["a"] === "string" &&
typeof p["b"] === "string" &&
typeof p["count"] === "number" &&
Number.isInteger(p["count"]) &&
(p["count"] as number) >= 0
);
}
/**
* Read the derived state; structurally invalid content reads as null -
* including corrupt NESTED rows, which would otherwise feed NaN into
* ranking. A null read falls back to the replayable event fold.
*/
export function readActivationState(vault: string | null): ActivationState | null {
try {
const parsed = JSON.parse(readFileSync(activationStatePath(vault), "utf8")) as ActivationState;
if (parsed.version !== 1) return null;
if (!Number.isInteger(parsed.events) || parsed.events < 0) return null;
if (!(parsed.updatedAt === null || typeof parsed.updatedAt === "string")) return null;
if (parsed.paths === null || typeof parsed.paths !== "object") return null;
if (!Array.isArray(parsed.coAccess)) return null;
for (const row of Object.values(parsed.paths as Record<string, unknown>)) {
if (!isPathState(row)) return null;
}
for (const pair of parsed.coAccess as ReadonlyArray<unknown>) {
if (!isCoAccessPair(pair)) return null;
}
return parsed;
} catch {
return null;
}
}
/**
* Stable fingerprint of the activation state for the query-cache key:
* "off" when no derived file exists, else a hash of its content.
*/
export function activationStateFingerprint(vault: string | null): string {
const path = activationStatePath(vault);
if (!existsSync(path)) return "off";
try {
return fnv1aHex(readFileSync(path, "utf8"));
} catch {
return "off";
}
}
export interface ActivationSweepOptions {
/** Injected clock (unix ms). */
readonly nowMs: number;
/** Events older than this many days are dropped. */
readonly retentionDays?: number;
/** At most this many newest events are kept. */
readonly maxEvents?: number;
}
/**
* Drop events outside the retention window or beyond the newest-N cap,
* then refold the derived state from what remains.
*/
export function sweepActivationEvents(
vault: string,
opts: ActivationSweepOptions,
): ActivationSweepOutcome {
const retentionDays = opts.retentionDays ?? ACCESS_EVENT_RETENTION_DAYS;
const maxEvents = opts.maxEvents ?? ACCESS_EVENT_MAX_COUNT;
const cutoff = opts.nowMs - retentionDays * DAY_MS;
const dir = activationDir(vault);
let files: string[];
try {
files = readdirSync(dir)
.filter((f) => f.endsWith(".json"))
.toSorted();
} catch {
// No event directory: refold a derived state that still exists so
// stale boosts never outlive their events.
if (existsSync(activationStatePath(vault))) {
writeActivationState(vault, computeActivationState([]));
}
return Object.freeze({ removed: 0, kept: 0 });
}
// Filename prefix is the event ts; malformed names parse as NaN and
// are treated as expired so junk never survives a sweep.
const withTs = files.map((f) => ({ f, ts: Number(f.split("-")[0]) }));
const fresh = withTs.filter((x) => Number.isFinite(x.ts) && x.ts >= cutoff);
const expired = withTs.filter((x) => !Number.isFinite(x.ts) || x.ts < cutoff);
fresh.sort((a, b) => a.ts - b.ts || a.f.localeCompare(b.f));
const overflow = fresh.length > maxEvents ? fresh.slice(0, fresh.length - maxEvents) : [];
const keep = fresh.slice(Math.max(0, fresh.length - maxEvents));
for (const x of [...expired, ...overflow]) {
rmSync(join(dir, x.f), { force: true });
}
writeActivationState(vault, computeActivationState(loadAccessEvents(vault)));
return Object.freeze({ removed: expired.length + overflow.length, kept: keep.length });
}