Skip to content

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
18.4 KB
Raw Blame
/**
 * 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 };
}