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
import { appendFileSync, mkdirSync } from "node:fs";
import { dirname, join } from "node:path";
import { interleaveShardRows, jsonlLedgerGrammar, readShardLinesByShard } from "./ledger-shards.ts";
import { BRAIN_LOG_REL } from "./path-constants.ts";
import { proceduralRecurrencePath, RECURRENCE_LEDGER_STEM } from "./paths.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { readLedgerRows } from "../store/read/ledger-rows.ts";
import { routeWrite } from "../store/store-write.ts";
import { DUAL_WRITE_LEDGERS, ledgerRowRecord } from "../store/dual-write-records.ts";
import { claimSourceIsPrivate, rowNamesPrivatePage } from "../store/reference-privacy.ts";
/** The recurrence ledger's file-name layout, handed to the shared shard grammar. */
const RECURRENCE_LEDGER_GRAMMAR = jsonlLedgerGrammar(RECURRENCE_LEDGER_STEM);
export type RecurrenceCommitment = "exploring" | "leaning" | "decided" | "locked";
export type RecurrenceAction = "learn" | "forget";
export interface RecurrenceThresholds {
readonly leaning: number;
readonly decided: number;
readonly locked: number;
}
export interface RecurrenceEventInput {
readonly contentHash: string;
readonly scope: string;
readonly sourceId: string;
readonly action: RecurrenceAction;
readonly at?: string;
}
export interface RecurrenceEntry {
readonly contentHash: string;
readonly supportCount: number;
readonly recurrenceCount: number;
readonly scopes: ReadonlyArray<{ scope: string; support: number }>;
readonly commitment: RecurrenceCommitment;
readonly sources: ReadonlyArray<{ sourceId: string; support: number }>;
}
interface RecurrenceEvent {
readonly kind: "support" | "purge-source";
readonly contentHash?: string;
readonly scope?: string;
readonly sourceId: string;
readonly action?: RecurrenceAction;
readonly at: string;
}
const DEFAULT_THRESHOLDS: RecurrenceThresholds = {
leaning: 3,
decided: 5,
locked: 8,
};
export function applyRecurrenceEvidence(
vault: string,
input: RecurrenceEventInput,
): RecurrenceEntry | null {
appendEvent(vault, {
kind: "support",
contentHash: input.contentHash,
scope: input.scope,
sourceId: input.sourceId,
action: input.action,
at: input.at ?? new Date().toISOString(),
});
return getRecurrenceEntry(vault, input.contentHash);
}
export function purgeRecurrenceSource(vault: string, sourceId: string, at?: string): void {
appendEvent(vault, {
kind: "purge-source",
sourceId,
at: at ?? new Date().toISOString(),
});
}
export function getRecurrenceEntry(
vault: string,
contentHash: string,
thresholds: RecurrenceThresholds = DEFAULT_THRESHOLDS,
): RecurrenceEntry | null {
return (
listRecurrenceEntries(vault, thresholds).find((entry) => entry.contentHash === contentHash) ??
null
);
}
/**
* Cadence projection for foresight (t_08a79c81): per surviving
* routine, the latest support timestamp and the mean interval between
* consecutive `learn` events. A single occurrence has no cadence
* (`meanIntervalDays: null`) and never projects forward. Purged
* sources are excluded globally - an approximation of the positional
* fold that can only under-project, never invent a routine.
*/
export interface RecurrenceCadence {
readonly contentHash: string;
readonly topScope: string;
readonly commitment: RecurrenceCommitment;
readonly supportCount: number;
readonly lastAt: string;
readonly meanIntervalDays: number | null;
}
export function listRecurrenceCadences(
vault: string,
thresholds: RecurrenceThresholds = DEFAULT_THRESHOLDS,
opts: RecurrenceReadOptions = {},
): ReadonlyArray<RecurrenceCadence> {
const entries = listRecurrenceEntries(vault, thresholds, opts);
if (entries.length === 0) return Object.freeze([]);
const events = readEvents(vault, opts);
const purged = new Set(events.filter((e) => e.kind === "purge-source").map((e) => e.sourceId));
const byHash = new Map<string, string[]>();
for (const e of events) {
if (e.kind !== "support" || !e.contentHash || e.action !== "learn") continue;
if (purged.has(e.sourceId)) continue;
const list = byHash.get(e.contentHash) ?? [];
list.push(e.at);
byHash.set(e.contentHash, list);
}
const out: RecurrenceCadence[] = [];
for (const entry of entries) {
const ats = (byHash.get(entry.contentHash) ?? [])
.map((at) => Date.parse(at))
.filter((ms) => Number.isFinite(ms))
.toSorted((a, b) => a - b);
if (ats.length === 0) continue;
let meanIntervalDays: number | null = null;
if (ats.length >= 2) {
const spanDays = (ats.at(-1)! - ats[0]!) / (24 * 3600 * 1000);
meanIntervalDays = Math.round((spanDays / (ats.length - 1)) * 10) / 10;
}
out.push(
Object.freeze({
contentHash: entry.contentHash,
topScope: entry.scopes[0]?.scope ?? "",
commitment: entry.commitment,
supportCount: entry.supportCount,
lastAt: new Date(ats.at(-1)!).toISOString(),
meanIntervalDays,
}),
);
}
out.sort((a, b) => (a.contentHash < b.contentHash ? -1 : a.contentHash > b.contentHash ? 1 : 0));
return Object.freeze(out);
}
export function listRecurrenceEntries(
vault: string,
thresholds: RecurrenceThresholds = DEFAULT_THRESHOLDS,
opts: RecurrenceReadOptions = {},
): ReadonlyArray<RecurrenceEntry> {
const events = readEvents(vault, opts);
const state = new Map<string, { supportBySourceScope: Map<string, number> }>();
for (const event of events) {
if (event.kind === "purge-source") {
for (const value of state.values()) {
for (const key of value.supportBySourceScope.keys()) {
if (key.endsWith(`\u0000${event.sourceId}`)) {
value.supportBySourceScope.delete(key);
}
}
}
continue;
}
if (!event.contentHash || !event.scope || !event.action) continue;
const bucket = state.get(event.contentHash) ?? {
supportBySourceScope: new Map<string, number>(),
};
const sourceScopeKey = `${event.scope}\u0000${event.sourceId}`;
const current = bucket.supportBySourceScope.get(sourceScopeKey) ?? 0;
if (event.action === "learn") {
bucket.supportBySourceScope.set(sourceScopeKey, current + 1);
} else {
if (current > 1) bucket.supportBySourceScope.set(sourceScopeKey, current - 1);
else bucket.supportBySourceScope.delete(sourceScopeKey);
}
state.set(event.contentHash, bucket);
}
const out: RecurrenceEntry[] = [];
for (const [contentHash, bucket] of state) {
const supportByScope = new Map<string, number>();
const supportBySource = new Map<string, number>();
for (const [sourceScopeKey, support] of bucket.supportBySourceScope) {
if (support < 1) continue;
const [scope, sourceId] = splitSourceScopeKey(sourceScopeKey);
if (!scope || !sourceId) continue;
supportByScope.set(scope, (supportByScope.get(scope) ?? 0) + support);
supportBySource.set(sourceId, (supportBySource.get(sourceId) ?? 0) + support);
}
const scopes = [...supportByScope.entries()]
.filter((item) => item[1] > 0)
.map(([scope, support]) => ({ scope, support }))
.toSorted((left, right) => left.scope.localeCompare(right.scope));
const sources = [...supportBySource.entries()]
.filter((item) => item[1] > 0)
.map(([sourceId, support]) => ({ sourceId, support }))
.toSorted((left, right) => left.sourceId.localeCompare(right.sourceId));
const supportCount = scopes.reduce((sum, item) => sum + item.support, 0);
if (supportCount < 1) continue;
out.push({
contentHash,
supportCount,
recurrenceCount: scopes.length,
scopes: Object.freeze(scopes),
commitment: commitmentForSupport(supportCount, thresholds),
sources: Object.freeze(sources),
});
}
return Object.freeze(
out.toSorted((left, right) => left.contentHash.localeCompare(right.contentHash)),
);
}
function splitSourceScopeKey(value: string): [string, string] {
const idx = value.indexOf("\u0000");
if (idx < 0) return ["", ""];
return [value.slice(0, idx), value.slice(idx + 1)];
}
function commitmentForSupport(
supportCount: number,
thresholds: RecurrenceThresholds,
): RecurrenceCommitment {
if (supportCount >= thresholds.locked) return "locked";
if (supportCount >= thresholds.decided) return "decided";
if (supportCount >= thresholds.leaning) return "leaning";
return "exploring";
}
function appendEvent(vault: string, event: RecurrenceEvent): void {
// One `recurrence` ledger row on a store-only machine (design D14 item
// 1), this device's legacy shard plus the dual write otherwise.
// `sourceId` and `scope` can name a page: a source that is a private
// page, or a page link that names none here, goes to `private` only.
routeWrite({
legacy: () => {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
// This device's shard (t_774dea61); the path helper confines it to the vault.
const path = proceduralRecurrencePath(vault);
mkdirSync(dirname(path), { recursive: true });
appendFileSync(path, `${JSON.stringify(event)}\n`, { encoding: "utf8" });
},
store: () =>
ledgerRowRecord(
DUAL_WRITE_LEDGERS.recurrence,
event,
claimSourceIsPrivate(vault, event.sourceId) || rowNamesPrivatePage(vault, event)
? "private"
: "shared",
),
context: { vault },
});
}
/**
* When an event happened, as the cross-device merge orders it. An event
* whose stamp does not parse sorts as early as possible, which in the
* merge means straight after the event its own shard holds before it.
*/
function eventTime(event: RecurrenceEvent): number {
const time = Date.parse(event.at);
return Number.isFinite(time) ? time : Number.NEGATIVE_INFINITY;
}
/** One ledger line as an event, or `null` for a torn line. */
function parseEvent(line: string): RecurrenceEvent | null {
try {
return JSON.parse(line) as RecurrenceEvent;
} catch {
return null;
}
}
/**
* Read options for the recurrence fold. With `excludePrivateEvents`,
* every support event the writer classified private is dropped BEFORE
* the fold - the same verdicts the writer applied at append time
* ({@link claimSourceIsPrivate} on the source, {@link rowNamesPrivatePage}
* on the row) - so an entry's scopes, support count and commitment are
* built only from evidence the caller may be shown, and no private
* scope string survives into a projected title.
*/
export interface RecurrenceReadOptions {
readonly excludePrivateEvents?: boolean;
}
function readEvents(vault: string, opts: RecurrenceReadOptions = {}): RecurrenceEvent[] {
// A store-only machine reads the `recurrence` ledger rows in fold order,
// the one order every machine agrees on (design D3).
const events = readLedgerRows<RecurrenceEvent>(DUAL_WRITE_LEDGERS.recurrence, readLegacyEvents, {
vault,
}).filter((event) => event !== null && typeof event === "object");
if (opts.excludePrivateEvents !== true) return events;
// Purge events carry no page name and only ever shrink the fold; the
// support events they purge are already judged individually.
return events.filter(
(event) =>
event.kind === "purge-source" ||
!(claimSourceIsPrivate(vault, event.sourceId) || rowNamesPrivatePage(vault, event)),
);
}
function readLegacyEvents(vault: string): RecurrenceEvent[] {
// Merged read over every device's shard (t_774dea61), interleaved by
// event time with each shard keeping its own file order. The fold is
// order-sensitive (`purge-source` deletes, `forget` decrements), so a
// shard-name order would replay one device's purge before another
// device's earlier learn and bring the purged source back. The absent
// directory lists nothing, which is the same empty result as before.
const shards = readShardLinesByShard(join(vault, BRAIN_LOG_REL), RECURRENCE_LEDGER_GRAMMAR).map(
(shard) => ({
shardId: shard.shardId,
rows: shard.rows.map(parseEvent).filter((event) => event !== null),
}),
);
return interleaveShardRows(shards, eventTime);
}