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
6.8 KB
Raw Blame
/**
 * The generic fold engine of the brain store (design D3, D4; task 1.6).
 *
 * Pure: no I/O, no clock. Every concrete fold (preferences, pinned
 * context, settings) is built from the two pieces here.
 *
 *  - {@link prepareRecords} turns any delivered set of verified records
 *    into one canonical sequence: duplicates collapse by record id (a
 *    record delivered twice is applied once), then the records sort in
 *    fold order (hlc, device, id). The same set gives the same sequence in
 *    any delivery order. Records whose body is still a pending blob
 *    reference are held out, since their content is not known yet.
 *  - {@link RegisterSet} resolves keyed registers by authority, then clock:
 *    a human record beats an agent record, which beats a decision-model
 *    record; within one authority the record later in fold order wins.
 *    Nothing is dropped: every offer stays in the register's history, so a
 *    losing value remains queryable. A removal is an ordinary offer whose
 *    value is the {@link TOMBSTONE}.
 *
 * Records whose kind a fold handles but whose body is malformed are not
 * applied; the fold reports them as rejected so doctor can name them.
 */

import { canonicalJson } from "../integrity/digest.ts";
import { compareCodeUnits } from "./compare.ts";
import { AUTHORITIES, AUTHORITY_FIELD, type Authority } from "./constants.ts";
import { compareRecords, isBlobRef, type StoreRecord } from "./envelope.ts";

/** The value of a register that a removal record decided. */
export const TOMBSTONE: unique symbol = Symbol("tombstone");
export type Tombstone = typeof TOMBSTONE;

/** A record a fold refused to apply, with the reason. */
export interface RejectedRecord {
  readonly id: string;
  readonly kind: string;
  readonly reason: string;
}

/** Two deliveries that share an id but not their content. */
export interface IdConflict {
  readonly id: string;
  /** Number of distinct versions delivered. */
  readonly versions: number;
}

export interface PreparedRecords {
  /** Unique records in fold order. */
  readonly records: ReadonlyArray<StoreRecord>;
  /** Deliveries dropped as exact duplicates of a record already seen. */
  readonly duplicates: number;
  /** Ids delivered with different content; one version was kept deterministically. */
  readonly conflicts: ReadonlyArray<IdConflict>;
  /** Records whose body is a blob that has not arrived (or not verified) yet. */
  readonly pending: ReadonlyArray<StoreRecord>;
}

/**
 * Pick the version of a conflicting id to keep: the smallest in fold
 * order, then by canonical text, so every machine keeps the same one.
 */
function preferVersion(a: StoreRecord, b: StoreRecord): StoreRecord {
  const order = compareRecords(a, b);
  if (order !== 0) return order < 0 ? a : b;
  return canonicalJson(a) <= canonicalJson(b) ? a : b;
}

/** Deduplicate by id, hold out pending bodies, and sort in fold order. */
export function prepareRecords(input: Iterable<StoreRecord>): PreparedRecords {
  const byId = new Map<string, StoreRecord>();
  // Canonical texts of every version delivered, kept only for repeated ids.
  const delivered = new Map<string, Set<string>>();
  let duplicates = 0;
  for (const record of input) {
    const seen = byId.get(record.id);
    if (seen === undefined) {
      byId.set(record.id, record);
      continue;
    }
    let texts = delivered.get(record.id);
    if (texts === undefined) {
      texts = new Set([canonicalJson(seen)]);
      delivered.set(record.id, texts);
    }
    const text = canonicalJson(record);
    if (texts.has(text)) {
      duplicates += 1; // an exact copy of a version already delivered
      continue;
    }
    texts.add(text);
    byId.set(record.id, preferVersion(seen, record));
  }
  const records: StoreRecord[] = [];
  const pending: StoreRecord[] = [];
  for (const record of byId.values()) (isBlobRef(record.body) ? pending : records).push(record);
  records.sort(compareRecords);
  pending.sort(compareRecords);
  const conflicts = [...delivered.entries()]
    .filter(([, texts]) => texts.size > 1)
    .map(([id, texts]) => ({ id, versions: texts.size }))
    .toSorted((a, b) => compareCodeUnits(a.id, b.id));
  return { records, duplicates, conflicts, pending };
}

/** Rank of an authority: higher beats lower. */
export function authorityRank(authority: Authority): number {
  return AUTHORITIES.length - AUTHORITIES.indexOf(authority);
}

/** Whether `value` names an authority. */
export function isAuthority(value: unknown): value is Authority {
  return typeof value === "string" && (AUTHORITIES as ReadonlyArray<string>).includes(value);
}

/**
 * The authority a mutable-entity record carries in its body, or `null`
 * when the field is missing or names no authority. It is never inferred
 * from the agent name.
 */
export function recordAuthority(record: StoreRecord): Authority | null {
  const value = record.body[AUTHORITY_FIELD];
  return isAuthority(value) ? value : null;
}

/** One offer to a register: who said what, and in which record. */
export interface RegisterEntry<V> {
  readonly record: StoreRecord;
  readonly authority: Authority;
  readonly value: V | Tombstone;
}

/** A resolved register. */
export interface RegisterState<V> {
  /** The winning value; `null` when a tombstone won. */
  readonly value: V | null;
  /** Whether a removal won. */
  readonly removed: boolean;
  /** The winning offer. */
  readonly winner: RegisterEntry<V>;
  /** Every offer in fold order, the winner included. */
  readonly history: ReadonlyArray<RegisterEntry<V>>;
}

/** Whether `next` beats `current`, given that `next` comes later in fold order. */
function beats(next: Authority, current: Authority): boolean {
  return authorityRank(next) >= authorityRank(current);
}

/**
 * Keyed registers resolved by authority, then fold order. Offers must
 * arrive in fold order (the order of {@link prepareRecords}); a later
 * offer of the same or a stronger authority takes the register.
 */
export class RegisterSet<V> {
  readonly #winners = new Map<string, RegisterEntry<V>>();
  readonly #history = new Map<string, RegisterEntry<V>[]>();

  offer(key: string, entry: RegisterEntry<V>): void {
    const current = this.#winners.get(key);
    if (current === undefined || beats(entry.authority, current.authority)) {
      this.#winners.set(key, entry);
    }
    const history = this.#history.get(key) ?? [];
    history.push(entry);
    this.#history.set(key, history);
  }

  get(key: string): RegisterState<V> | undefined {
    const winner = this.#winners.get(key);
    if (winner === undefined) return undefined;
    const removed = winner.value === TOMBSTONE;
    return {
      value: removed ? null : (winner.value as V),
      removed,
      winner,
      history: this.#history.get(key)!,
    };
  }

  /** Keys in code unit order. */
  keys(): string[] {
    return [...this.#winners.keys()].toSorted();
  }
}