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
12.0 KB
Raw Blame
/**
 * The store records each legacy writer produces under dual writes (task
 * 1.11). One builder per legacy surface, so the mapping from the legacy
 * tree to the store is written down in one place:
 *
 *  - a signal file             -> `signal` in `events`
 *  - a Brain log event         -> `log-event` in `log`
 *  - a preference write/retire -> `preference-set` in `events`
 *  - apply-evidence            -> `preference-evidence` in `events`
 *  - pinned context            -> `pinned-set` / `pinned-clear` in `events`
 *  - a per-device ledger row   -> `ledger-row` in `ledgers/<name>`
 *
 * Authority (FORMAT.md, "Authority") is never inferred here: the legacy
 * caller passes it, usually from `authorityFromOrigin()`.
 *
 * Bodies are plain JSON: values are passed through a JSON round trip so a
 * `Date` or an `undefined` in a legacy structure cannot make the checksum
 * depend on how a value happens to serialise.
 */

import { existsSync } from "node:fs";
import { relative, sep } from "node:path";

import { preferencePath, retiredPath } from "../brain/paths.ts";
import {
  AUTHORITY_FIELD,
  LEDGER_ROW_KIND,
  LOG_EVENT_KIND,
  PINNED_CLEAR_KIND,
  PINNED_SET_KIND,
  PREFERENCE_COUNTER_FIELDS,
  PREFERENCE_EVIDENCE_KIND,
  PREFERENCE_SET_KIND,
  SIGNAL_KIND,
  type Authority,
  type EvidenceResult,
} from "./constants.ts";
import type { DualWriteRecord } from "./dual-write.ts";
import type { RecordBody } from "./envelope.ts";
import { PREFERENCE_FIELD_RE } from "./fold-preferences.ts";
import { isPrivatePageFile } from "./private-page.ts";
import { judgesFromStore, storePreferenceIdIsPrivate } from "./store-privacy.ts";

export { isPrivateFrontmatter, isPrivatePageFile } from "./private-page.ts";

const COUNTERS = new Set<string>(PREFERENCE_COUNTER_FIELDS);

function plain<T>(value: T): T {
  return JSON.parse(JSON.stringify(value ?? null)) as T;
}

/** `path` relative to `vault`; with no vault (`null`) it is already vault-relative. */
function vaultRel(vault: string | null, path: string): string {
  return (vault === null ? path : relative(vault, path)).split(sep).join("/");
}

function textOf(value: unknown): string | null {
  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
}

/**
 * Whether the preference `pref-<slug>` (active or retired) is private, so
 * the log events and ledger rows that name it stay out of `shared`. A
 * preference with no file reads as not private. On a store-only machine,
 * or with no vault, the preference fold decides instead, and a preference
 * the fold does not hold is private (design D14 item 18).
 */
export function isPrivatePreference(vault: string | null, slug: string): boolean {
  if (vault === null || judgesFromStore(vault)) return storePreferenceIdIsPrivate(`pref-${slug}`);
  for (const path of [preferencePath(vault, slug), retiredPath(vault, slug)]) {
    if (existsSync(path) && isPrivatePageFile(path)) return true;
  }
  return false;
}

/**
 * A signal file the legacy writer created, in the partition of the write's
 * single privacy verdict (`operation-privacy.ts`).
 */
export function signalRecord(input: {
  readonly vault: string | null;
  readonly path: string;
  readonly id: string;
  readonly staged: boolean;
  readonly frontmatter: Readonly<Record<string, unknown>>;
  readonly raw: string | undefined;
  /** What `raw` holds (FORMAT.md, `signal`): the captured text (default) or an imported page body. */
  readonly rawShape?: SignalRawShape;
  readonly private: boolean;
}): DualWriteRecord {
  const frontmatter = plain(input.frontmatter) as Record<string, unknown>;
  return {
    stream: "events",
    kind: SIGNAL_KIND,
    agent: textOf(frontmatter["agent"]) ?? undefined,
    scope: textOf(frontmatter["scope"]),
    private: input.private,
    body: {
      id: input.id,
      path: vaultRel(input.vault, input.path),
      staged: input.staged,
      frontmatter,
      raw: input.raw ?? null,
      ...(input.raw !== undefined ? { [SIGNAL_RAW_SHAPE_FIELD]: input.rawShape ?? "bare" } : {}),
    },
  };
}

/** What a `signal` record's `raw` holds: the captured text, or an imported page's body. */
export type SignalRawShape = "bare" | "page";

/** Body field of a `signal` record naming its {@link SignalRawShape}. */
export const SIGNAL_RAW_SHAPE_FIELD = "raw_shape";

/**
 * The {@link SignalRawShape} of a `signal` record's body: its `raw_shape`,
 * or, for a record written before the field existed, `page` when one of
 * the first three lines of `raw` is the `## Raw` heading.
 */
export function signalRawShape(body: Readonly<Record<string, unknown>>): SignalRawShape {
  const marked = body[SIGNAL_RAW_SHAPE_FIELD];
  if (marked === "bare" || marked === "page") return marked;
  const raw = body["raw"];
  return typeof raw === "string" && /^\s*## Raw\s*$/m.test(raw.split("\n", 3).join("\n"))
    ? "page"
    : "bare";
}

/** One Brain log event, as the legacy appender wrote it. */
export function logEventRecord(
  event: {
    readonly timestamp: string;
    readonly eventType: string;
    readonly agent?: string;
    readonly body: Readonly<Record<string, unknown>>;
  },
  /** `true` when the event names a private item (a private preference). */
  isPrivate = false,
): DualWriteRecord {
  const body = plain(event.body) as Record<string, unknown>;
  return {
    stream: "log",
    kind: LOG_EVENT_KIND,
    agent: textOf(body["agent"]) ?? textOf(event.agent) ?? undefined,
    private: isPrivate,
    body: { timestamp: event.timestamp, event_type: event.eventType, body },
  };
}

/**
 * The fields a preference record carries: every frontmatter key that is a
 * valid field name, minus the counters (derived from evidence in the fold,
 * never written back). A `null` value is kept: it says the field is unset.
 */
export function preferenceFields(
  frontmatter: Readonly<Record<string, unknown>>,
): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const [name, value] of Object.entries(plain(frontmatter) as Record<string, unknown>)) {
    if (!PREFERENCE_FIELD_RE.test(name) || COUNTERS.has(name)) continue;
    out[name] = value;
  }
  return out;
}

/**
 * A preference as the legacy writer just wrote (or retired) it, in the
 * partition of the write's single privacy verdict (`operation-privacy.ts`).
 */
export function preferenceSetRecord(input: {
  readonly id: string;
  readonly frontmatter: Readonly<Record<string, unknown>>;
  readonly authority: Authority;
  readonly agent?: string;
  readonly private: boolean;
}): DualWriteRecord | null {
  const fields = preferenceFields(input.frontmatter);
  if (Object.keys(fields).length === 0) return null;
  return {
    stream: "events",
    kind: PREFERENCE_SET_KIND,
    ...(input.agent !== undefined ? { agent: input.agent } : {}),
    scope: textOf(fields["scope"]),
    private: input.private,
    body: { [AUTHORITY_FIELD]: input.authority, preference: input.id, fields },
  };
}

/** One application of a preference (`brain_apply_evidence`). */
export function preferenceEvidenceRecord(input: {
  readonly id: string;
  readonly result: EvidenceResult;
  readonly artifact: string;
  readonly agent: string;
  readonly private: boolean;
  /** The evidence record this one copies (a merge moving a drop's evidence to the keep). */
  readonly mergedFrom?: string;
}): DualWriteRecord {
  return {
    stream: "events",
    kind: PREFERENCE_EVIDENCE_KIND,
    agent: input.agent,
    private: input.private,
    body: {
      preference: input.id,
      result: input.result,
      artifact: input.artifact,
      ...(input.mergedFrom !== undefined ? { [MERGED_FROM_FIELD]: input.mergedFrom } : {}),
    },
  };
}

/**
 * Body field of a `preference-evidence` record a merge copied from the
 * dropped preference: the id of the record it copies, so a merge retried
 * after a partial run copies each record once.
 */
export const MERGED_FROM_FIELD = "merged_from";

/**
 * The pinned context after a legacy write: its full text, or `null` for a
 * clear. Pinned facts are often drawn from the notes an agent is working
 * on, so the record goes to `private` when this machine holds it and to
 * `shared` when it does not. A text that carries a `<private>` region or
 * names a private page (`namesPrivate`, `pinnedTextIsPrivate` in
 * `reference-privacy.ts`) goes to `private` only; a clear is judged by the
 * text it clears, so it lands where that text's set did.
 */
export function pinnedRecord(
  content: string | null,
  authority: Authority,
  namesPrivate: boolean,
): DualWriteRecord {
  const body: RecordBody =
    content === null ? { [AUTHORITY_FIELD]: authority } : { [AUTHORITY_FIELD]: authority, content };
  return {
    stream: "events",
    kind: content === null ? PINNED_CLEAR_KIND : PINNED_SET_KIND,
    ...partitionOf(namesPrivate ? "private" : "private-when-held"),
    body,
  };
}

/**
 * Where a ledger row goes. Every ledger site states it, so a new site
 * cannot fall into `shared` by default:
 *
 *  - `private`: the row names a private item (a private preference, a
 *    private page, a turn with a `<private>` region); on a machine without
 *    that partition the appender refuses it and the refusal is counted;
 *  - `private-when-held`: the row says what this machine or its user did
 *    (audit trails, session lineage, search terms) and names no private
 *    page; it goes to `private` when this machine holds it, else `shared`;
 *  - `shared`: the row carries nothing about the user's private notes.
 */
export type RowPartition = "shared" | "private" | "private-when-held";

function partitionOf(
  partition: RowPartition,
): Pick<DualWriteRecord, "private" | "privateWhenHeld"> {
  return {
    private: partition === "private",
    ...(partition === "private-when-held" ? { privateWhenHeld: true } : {}),
  };
}

/** One row of a per-device legacy ledger, under `ledgers/<name>`, in the partition its caller states. */
export function ledgerRowRecord(
  ledger: string,
  row: unknown,
  partition: RowPartition,
  agent?: string,
): DualWriteRecord {
  return {
    stream: "ledgers",
    ledger,
    kind: LEDGER_ROW_KIND,
    ...(agent !== undefined ? { agent } : {}),
    ...partitionOf(partition),
    body: { row: plain(row) },
  };
}

/**
 * One `truth-claims` ledger row. A claim taken from a private page
 * (`sourceIsPrivate`, `reference-privacy.ts`) goes to `private` only; any
 * other claim goes to `private` when this machine holds it and to
 * `shared` when it does not.
 */
export function truthClaimRowRecord(row: unknown, sourceIsPrivate: boolean): DualWriteRecord {
  return ledgerRowRecord(
    DUAL_WRITE_LEDGERS.truthClaims,
    row,
    sourceIsPrivate ? "private" : "private-when-held",
  );
}

/**
 * One row of an audit trail: the `preference-audit` ledger, or the
 * `reliability-audit` ledger that every `Brain/log/<trail>/` audit shares
 * (hygiene, secret custody, hook audit, watchdog, ...). Audit rows say who
 * did what to which item, so they go to `private` when this machine holds
 * it and to `shared` when it does not. A row about a private item passes
 * `isPrivate` and goes only to `private`: on a machine without that
 * partition the appender refuses it, as for any private record.
 */
export function auditRowRecord(
  ledger: typeof DUAL_WRITE_LEDGERS.preferenceAudit | typeof DUAL_WRITE_LEDGERS.reliabilityAudit,
  row: unknown,
  agent: string | undefined,
  isPrivate: boolean,
): DualWriteRecord {
  return ledgerRowRecord(ledger, row, isPrivate ? "private" : "private-when-held", agent);
}

/**
 * Store ledger names of the per-device legacy ledgers that dual-write
 * their rows (`ledgers/<name>/<device>/<YYYY-MM>.jsonl`).
 */
export const DUAL_WRITE_LEDGERS = Object.freeze({
  idempotency: "idempotency",
  continuity: "continuity",
  metrics: "metrics",
  lineage: "lineage",
  permissions: "permissions",
  gitCommits: "git-commits",
  reliabilityAudit: "reliability-audit",
  maintenanceJournal: "maintenance-journal",
  verifierRejections: "verifier-rejections",
  preferenceAudit: "preference-audit",
  editHistory: "edit-history",
  decisionReceipts: "decision-receipts",
  truthClaims: "truth-claims",
  queryDemand: "query-demand",
  recurrence: "recurrence",
} as const);