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
/**
* Per-session injection ledger: what the context-injecting hooks already put
* in front of the agent this session, and the queue of active-digest parts
* still to re-deliver after a split.
*
* Four namespaced keys live in the per-scope hook-state file
* (`session-state.ts`); this module is the only one that spells them:
*
* - {@link LEDGER_KEY_RECALL}: recall note keys already injected, so a later
* prompt does not repeat them.
* - {@link LEDGER_KEY_ACTIVE}: vault paths the SessionStart digest emitted.
* - {@link LEDGER_KEY_REGROUND}: digest parts 2..n plus a delivery cursor.
* - {@link LEDGER_KEY_SUBAGENT_INJECT}: sub-agent ids the PostToolUse
* carrier already delivered the standing rules to, plus the
* vault-relative note paths the delivered payload was built from (the
* evidence an answer-time quote check may verify that sub-agent's
* quoted spans against).
* - {@link LEDGER_KEY_COUNTERPARTY_BRIEF}: the entity id the counterparty
* brief was delivered for, so the brief rides the first qualifying turn
* of a session only (dated commitments, t_43b0a379).
*
* Every entry carries a {@link LEDGER_TTL_MS} expiry refreshed on each write.
* Readers degrade to "empty" on any failure and never throw; writers return
* `false` rather than throwing, so the hooks stay fail-open.
*/
import { parseHookStamp, readHookStamp, updateHookState } from "./session-state.ts";
export const LEDGER_KEY_RECALL = "osb.recall_inject.injected";
export const LEDGER_KEY_ACTIVE = "osb.active_inject.emitted";
export const LEDGER_KEY_REGROUND = "osb.reground.queue";
export const LEDGER_KEY_SUBAGENT_INJECT = "osb.subagent_inject.delivered";
export const LEDGER_KEY_COUNTERPARTY_BRIEF = "osb.counterparty_brief.delivered";
/** Lifetime of every ledger entry (24 h), refreshed on every write. */
export const LEDGER_TTL_MS = 86_400_000;
/**
* Ceiling on the recall set: only the most recent keys are kept, so a long
* session without a new SessionStart cannot grow the scope file that every
* lock-free reader re-parses on each prompt and tool call.
*/
export const RECALL_SET_MAX = 2000;
/**
* Ceiling on the sub-agent delivery set, for the same reason the recall set
* is capped: a delegated sub-agent is delivered to once per session, so a
* session that spawns hundreds of them must not grow the scope file that
* every lock-free reader re-parses on each write-shaped tool call. A session
* with more distinct sub-agents than the cap starts re-delivering to the
* oldest ids, which is the lose-not-duplicate side the carrier already
* accepts for a failed write.
*/
export const SUBAGENT_SET_MAX = 200;
/**
* Ceiling on the delivered-evidence path set recorded beside the ids: one
* delivery names a handful of note files, but a session that spawns many
* sub-agents across a large vault must not grow the scope file that every
* lock-free reader re-parses. Past the cap the oldest paths drop first,
* like the ids beside them.
*/
export const SUBAGENT_PATHS_MAX = 200;
/**
* True only for a string session id with at least one ASCII alphanumeric, the
* same floor `resolveSessionScope` needs; anything less would collapse to the
* shared default scope. A sessionless host gets no ledger at all, so one
* host's recall can never suppress another's through that scope.
*/
export function isRealSessionId(sessionId: unknown): sessionId is string {
return typeof sessionId === "string" && /[A-Za-z0-9]/.test(sessionId);
}
/** The string members of `value` when it is an array, else an empty list. */
function stringList(value: unknown): string[] {
if (!Array.isArray(value)) return [];
return value.filter((item): item is string => typeof item === "string");
}
/** Read one ledger key's raw array field; empty when absent or expired. */
function readRawList(
vault: string,
sessionId: string,
key: string,
field: string,
nowMs: number,
): unknown[] {
const stamp = readHookStamp(vault, sessionId, key, nowMs);
const value = stamp?.data?.[field];
return Array.isArray(value) ? value : [];
}
/** Read one ledger key's string-array field as a set; empty when absent or expired. */
function readStringSet(
vault: string,
sessionId: string,
key: string,
field: string,
nowMs: number,
): ReadonlySet<string> {
const stamp = readHookStamp(vault, sessionId, key, nowMs);
return new Set(stringList(stamp?.data?.[field]));
}
/** Recall note keys already injected this session. */
export function readRecallInjected(
vault: string,
sessionId: string,
nowMs: number = Date.now(),
): ReadonlySet<string> {
return readStringSet(vault, sessionId, LEDGER_KEY_RECALL, "keys", nowMs);
}
/**
* Merge `keys` into the session's injected set and refresh its expiry. An
* expired set is dropped rather than merged. Past {@link RECALL_SET_MAX}
* keys the oldest drop first (a re-recorded key keeps its first position,
* which is enough for a dedupe hint). Returns `false` on any failure.
*/
export function recordRecallInjected(
vault: string,
sessionId: string,
keys: ReadonlyArray<string>,
nowMs: number = Date.now(),
): boolean {
const outcome = updateHookState(
vault,
sessionId,
(state, now) => {
const prior = liveData(state[LEDGER_KEY_RECALL], now);
const merged = new Set([...stringList(prior?.["keys"]), ...keys]);
const all = [...merged];
state[LEDGER_KEY_RECALL] = {
expiresAt: now + LEDGER_TTL_MS,
data: { keys: all.slice(Math.max(0, all.length - RECALL_SET_MAX)) },
};
return { state, result: true };
},
{ nowMs },
);
return outcome.status === "ok";
}
/** Sub-agent ids the standing-rules carrier already delivered to this session. */
export function readSubagentDeliveredIds(
vault: string,
sessionId: string,
nowMs: number = Date.now(),
): ReadonlySet<string> {
return readStringSet(vault, sessionId, LEDGER_KEY_SUBAGENT_INJECT, "ids", nowMs);
}
/**
* Vault-relative note paths the delivered carrier payloads were built from
* this session (answer-trust wave): the evidence a sub-agent turn can be
* quoted against. A truncated delivery - the payload carried only a
* prefix of the note - records `{ path, truncated: true }`, because the
* evidence is the prefix, not the file; a plain string names a whole-note
* delivery. Rows recorded before the paths field existed - and deliveries
* whose payload carried no note content - read as an empty list, so an
* old ledger row is silence for the quote check, never an error.
*/
export type SubagentEvidencePath = string | { readonly path: string; readonly truncated: boolean };
function evidencePathEntry(value: unknown): SubagentEvidencePath | null {
if (typeof value === "string" && value.length > 0) return value;
if (typeof value === "object" && value !== null && "path" in value) {
const record = value as { path: unknown; truncated?: unknown };
if (typeof record.path === "string" && record.path.length > 0) {
return { path: record.path, truncated: record.truncated === true };
}
}
return null;
}
export function readSubagentDeliveredPaths(
vault: string,
sessionId: string,
nowMs: number = Date.now(),
): ReadonlyArray<SubagentEvidencePath> {
const raw = readRawList(vault, sessionId, LEDGER_KEY_SUBAGENT_INJECT, "paths", nowMs);
const byPath = new Map<string, SubagentEvidencePath>();
for (const item of raw) {
const entry = evidencePathEntry(item);
if (entry === null) continue;
const path = typeof entry === "string" ? entry : entry.path;
const prior = byPath.get(path);
// Truncation is sticky: once a delivery named a clipped prefix of a
// note, later whole-string rows cannot widen the evidence back.
if (prior === undefined) {
byPath.set(path, entry);
} else if (typeof entry === "object" && entry.truncated) {
byPath.set(path, entry);
}
}
return [...byPath.values()];
}
/**
* Merge `agentId` - and the `evidencePaths` the delivered payload was
* built from, when the carrier names any - into the session's delivered
* record and refresh its expiry. Paths are a second list beside the ids
* and merge the same way: a re-delivery without paths keeps what earlier
* deliveries merged, so evidence already handed to this session's
* sub-agents stays named. An expired record is dropped rather than
* merged. Past {@link SUBAGENT_SET_MAX} ids and {@link SUBAGENT_PATHS_MAX}
* paths the oldest drop first (a re-delivered id keeps its first position,
* which is enough for a dedupe hint). Returns `false` on any failure.
*/
export function recordSubagentDeliveredId(
vault: string,
sessionId: string,
agentId: string,
evidencePaths: ReadonlyArray<SubagentEvidencePath> = [],
nowMs: number = Date.now(),
): boolean {
const outcome = updateHookState(
vault,
sessionId,
(state, now) => {
const prior = liveData(state[LEDGER_KEY_SUBAGENT_INJECT], now);
const mergedIds = new Set([...stringList(prior?.["ids"]), agentId]);
const allIds = [...mergedIds];
// Path-keyed merge; a truncated entry (the payload carried only a
// prefix) is sticky over a plain whole-note row of the same path.
const merged = new Map<string, SubagentEvidencePath>();
for (const item of [
...(Array.isArray(prior?.["paths"]) ? prior["paths"] : []),
...evidencePaths,
]) {
const entry = evidencePathEntry(item);
if (entry === null) continue;
const path = typeof entry === "string" ? entry : entry.path;
const priorEntry = merged.get(path);
if (priorEntry === undefined) {
merged.set(path, entry);
} else if (typeof entry === "object" && entry.truncated) {
merged.set(path, entry);
}
}
const allPaths = [...merged.values()];
state[LEDGER_KEY_SUBAGENT_INJECT] = {
expiresAt: now + LEDGER_TTL_MS,
data: {
ids: allIds.slice(Math.max(0, allIds.length - SUBAGENT_SET_MAX)),
...(allPaths.length > 0
? { paths: allPaths.slice(Math.max(0, allPaths.length - SUBAGENT_PATHS_MAX)) }
: {}),
},
};
return { state, result: true };
},
{ nowMs },
);
return outcome.status === "ok";
}
/** Vault paths the active digest emitted in the current epoch. */
export function readActiveEmittedPaths(
vault: string,
sessionId: string,
nowMs: number = Date.now(),
): ReadonlySet<string> {
return readStringSet(vault, sessionId, LEDGER_KEY_ACTIVE, "paths", nowMs);
}
/**
* The entity id the counterparty brief was already delivered for this
* session, or null. The key is the whole brief's suppressant, not a
* per-entity set: the hook emits at most one brief per session, so any
* non-null answer suppresses the next qualifying turn.
*/
export function readBriefDelivered(
vault: string,
sessionId: string,
nowMs: number = Date.now(),
): string | null {
const stamp = readHookStamp(vault, sessionId, LEDGER_KEY_COUNTERPARTY_BRIEF, nowMs);
const entityId = stamp?.data?.["entityId"];
return typeof entityId === "string" && entityId.length > 0 ? entityId : null;
}
/**
* Record the entity id the counterparty brief was delivered for, with the
* ledger's standard TTL. Returns `false` on any failure; the hook treats a
* failed record as a possible one-brief repeat, never as a reason to
* withhold a brief it already printed.
*/
export function recordBriefDelivered(
vault: string,
sessionId: string,
entityId: string,
nowMs: number = Date.now(),
): boolean {
const outcome = updateHookState(
vault,
sessionId,
(state, now) => {
state[LEDGER_KEY_COUNTERPARTY_BRIEF] = {
expiresAt: now + LEDGER_TTL_MS,
data: { entityId },
};
return { state, result: true };
},
{ nowMs },
);
return outcome.status === "ok";
}
/**
* A preference bullet as the active digest renders it: a line that starts
* with `` - `pref-<slug>` `` followed by a space or the line end (see
* `renderConfirmedLine` and its siblings in src/core/brain/active.ts). A
* backticked `pref-` token anywhere else in a line, such as a lesson or a
* prose line quoting one, is not a rendered preference and does not match.
*/
const PREF_BULLET_RE = /^- `pref-([A-Za-z0-9][A-Za-z0-9_-]*)`(?=[ \t\r]|$)/gm;
/**
* Vault paths a digest emission covers: `Brain/active.md` and
* `Brain/lessons.md` when their bodies were emitted, then one
* `Brain/preferences/pref-<slug>.md` per rendered preference bullet, in
* first-seen order with repeats dropped. Only the bullet shape counts, so
* vault text that merely quotes a preference id cannot suppress its recall.
*/
export function digestNotePaths(input: {
readonly emittedText: string;
readonly activeBodyEmitted: boolean;
readonly lessonsBodyEmitted: boolean;
}): ReadonlyArray<string> {
const paths = new Set<string>();
if (input.activeBodyEmitted) paths.add("Brain/active.md");
if (input.lessonsBodyEmitted) paths.add("Brain/lessons.md");
for (const match of input.emittedText.matchAll(PREF_BULLET_RE)) {
paths.add(`Brain/preferences/pref-${match[1]}.md`);
}
return [...paths];
}
/**
* Start a new injection epoch in one locked write: record the digest's
* emitted paths, clear the recall set (the new digest supersedes what recall
* already showed), and replace the re-delivery queue with `regroundParts`
* (parts 2..n), or delete it when there are none. Returns `false` on any
* failure.
*/
export function beginInjectionEpoch(
vault: string,
sessionId: string,
input: {
readonly epoch: string;
readonly emittedPaths: ReadonlyArray<string>;
readonly regroundParts: ReadonlyArray<string>;
readonly partCeilingChars: number;
},
nowMs: number = Date.now(),
): boolean {
const outcome = updateHookState(
vault,
sessionId,
(state, now) => {
const expiresAt = now + LEDGER_TTL_MS;
state[LEDGER_KEY_ACTIVE] = {
expiresAt,
data: { epoch: input.epoch, paths: [...new Set(input.emittedPaths)] },
};
delete state[LEDGER_KEY_RECALL];
if (input.regroundParts.length === 0) {
delete state[LEDGER_KEY_REGROUND];
} else {
state[LEDGER_KEY_REGROUND] = {
expiresAt,
data: {
epoch: input.epoch,
parts: [...input.regroundParts],
next: 0,
partCeilingChars: input.partCeilingChars,
},
};
}
return { state, result: true };
},
{ nowMs },
);
return outcome.status === "ok";
}
/** Result of {@link takeRegroundPart}. */
export type RegroundTake =
| {
readonly status: "part";
readonly part: string;
/** 1-based position in the full split (the first queued part is 2). */
readonly index: number;
readonly total: number;
readonly epoch: string;
readonly partCeilingChars: number;
}
| { readonly status: "empty" }
| { readonly status: "busy" }
| {
readonly status: "failed";
/** Epoch of the queue the lock-free pre-check read; `null` when malformed. */
readonly epoch: string | null;
};
/** The `data` record of a live (unexpired) stamp in raw state, else `null`. */
function liveData(raw: unknown, nowMs: number): Record<string, unknown> | null {
return parseHookStamp(raw, nowMs)?.data ?? null;
}
/** A validated re-delivery queue. */
interface RegroundQueue {
readonly epoch: string;
readonly parts: string[];
readonly next: number;
readonly partCeilingChars: number;
}
/** Parse a queue payload; `null` when any field is missing or malformed. */
function parseQueue(data: Record<string, unknown> | null): RegroundQueue | null {
if (data === null) return null;
const { epoch, parts, next, partCeilingChars } = data;
if (typeof epoch !== "string") return null;
if (!Array.isArray(parts) || !parts.every((p) => typeof p === "string")) return null;
if (typeof next !== "number" || !Number.isInteger(next) || next < 0) return null;
if (typeof partCeilingChars !== "number" || !Number.isFinite(partCeilingChars)) return null;
return { epoch, parts: parts as string[], next, partCeilingChars };
}
/**
* Hand out the next queued digest part exactly once. One lock attempt, no
* retry: on contention it returns `busy` and the caller emits nothing, so the
* part stays queued for the next event. The cursor advance is persisted
* before the part is returned, so a crash after the write loses that part and
* never duplicates it. The queue key is deleted once its last part is taken.
* A queue whose epoch is not the active epoch reads as empty and is
* deleted; in practice that is an expired active stamp or a hand-edited
* state file. The gate does NOT catch a failed SessionStart replacement:
* {@link beginInjectionEpoch} writes the active epoch and the queue in one
* atomic write, so when that write fails, and so does the retry
* active-inject makes after printing the whole payload, both old keys
* survive with matching epochs and the following takes still hand out the
* earlier SessionStart's remaining parts, one per event. A missing queue is
* answered from a lock-free read, without taking the lock or writing.
*/
export function takeRegroundPart(
vault: string,
sessionId: string,
nowMs: number = Date.now(),
): RegroundTake {
const stamp = readHookStamp(vault, sessionId, LEDGER_KEY_REGROUND, nowMs);
if (stamp === null) return { status: "empty" };
const outcome = updateHookState<RegroundTake>(
vault,
sessionId,
(state, now) => {
const queue = parseQueue(liveData(state[LEDGER_KEY_REGROUND], now));
const activeEpoch = liveData(state[LEDGER_KEY_ACTIVE], now)?.["epoch"];
if (queue === null || queue.epoch !== activeEpoch || queue.next >= queue.parts.length) {
delete state[LEDGER_KEY_REGROUND];
return { state, result: { status: "empty" } };
}
const position = queue.next;
if (position + 1 >= queue.parts.length) {
delete state[LEDGER_KEY_REGROUND];
} else {
state[LEDGER_KEY_REGROUND] = {
expiresAt: now + LEDGER_TTL_MS,
data: { ...queue, next: position + 1 },
};
}
return {
state,
result: {
status: "part",
part: queue.parts[position]!,
index: position + 2,
total: queue.parts.length + 1,
epoch: queue.epoch,
partCeilingChars: queue.partCeilingChars,
},
};
},
{ tryOnce: true, nowMs },
);
if (outcome.status === "ok") return outcome.result;
if (outcome.status === "busy") return outcome;
const epoch = stamp.data?.["epoch"];
return { status: "failed", epoch: typeof epoch === "string" ? epoch : null };
}