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
11.2 KB
Raw Blame
/**
 * Human edits of topic pages as topic records (spec `topics` "Human edits
 * win"; task 3.2). A line of `topic.md` or `archive.md` carries a key
 * `t:<topic id>:<what>` (`topic-pages.ts`); an edit of that line becomes
 * the topic record that says the same thing, with `human` authority, so
 * it beats every agent and decision-model record on that item and moves
 * with the topic through a rename:
 *
 *  - the title line: `topic-rename` of the title; the description line:
 *    `topic-rename` of the description (deleted: cleared);
 *  - the status line: `topic-status`, when the text names a status in any
 *    language the view has (a done date in brackets is kept);
 *  - the goal line: `topic-goal` (deleted: cleared);
 *  - a milestone, decision, open question or log line reworded: the
 *    item's record with the new text (a milestone ticked `[x]` also gets a
 *    `milestone-done`); deleted: the item's tombstone;
 *  - a goal proposal deleted: an `undo` of the agent's goal record;
 *    reworded: the user's own goal;
 *  - a line added under a section heading or item: a new item of that
 *    section (a line added to the log is a `note`), whose id comes from its
 *    topic, section and text, so one line added twice is one item.
 *
 * Generated decorations (the list marker, a checkbox, the done or "looks
 * done" marker, the date and class of a log line, "serves" and answer
 * tails) are stripped in every language before the text is stored. Any
 * other line (headings, the related section, a status that names no
 * status) is not mapped here: `null` sends it to the generic correction
 * of the view (`corrections.ts`).
 */

import { sha256Hex } from "../integrity/digest.ts";
import { TOPIC_STATUSES, type TopicItemKind, type TopicStatus } from "../topics/constants.ts";
import { topicBodyRejection } from "../topics/records.ts";
import type { EditRecord } from "./edit-record.ts";
import { allViewStrings } from "./i18n.ts";

const KEY_RE = /^t:([0-9A-HJKMNP-TV-Z]{26}):(.+)$/;
const LIST_MARKER_RE = /^\s*(?:[-*+]|\d+[.)])\s+/;
const CHECKBOX_RE = /^\[( |x|X)\]\s*/;
const DAY = "\\d{4}-\\d{2}-\\d{2}";

const escape = (text: string): string => text.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");

/** A pattern from a template: each hole is the source text of its group. */
function template(text: string, holes: ReadonlyArray<string>): string {
  let out = escape(text);
  holes.forEach((hole, i) => {
    out = out.replace(String.fromCharCode(i + 1), hole);
  });
  return out;
}

const STRINGS = allViewStrings();
const alt = (parts: ReadonlyArray<string>): string => parts.join("|");

const MILESTONE_TAIL_RE = new RegExp(
  `\\s*\\((?:${alt(STRINGS.flatMap((s) => [template(s.milestoneDone("\u0001"), [DAY]), escape(s.milestoneLooksDone)]))})\\)\\s*$`,
);
const DECISION_TAIL_RE = new RegExp(
  `\\s*\\((?:${alt(STRINGS.map((s) => template(s.serves("\u0001"), [".*"])))})\\)\\s*$`,
);
const QUESTION_TAIL_RE = new RegExp(
  `\\s*\\((?:${alt(STRINGS.flatMap((s) => [template(s.questionAnswer("\u0001"), [".*"]), escape(s.questionLooksAnswered)]))})\\)\\s*$`,
);
const LOG_HEAD_RE = new RegExp(
  `^${DAY},\\s*(?:${alt(STRINGS.flatMap((s) => Object.values(s.logClass).map(escape)))}):\\s*`,
  "i",
);
const BECAUSE_RE = new RegExp(
  `,\\s*(?:${alt(STRINGS.map((s) => template(s.because("\u0001"), ["(.+)"])))})$`,
);
const GOAL_PROPOSAL_RE = new RegExp(
  `^(?:${alt(STRINGS.map((s) => template(s.goalProposal("\u0001", "\u0002"), [".+?", "(.+)"])))})$`,
);

function human(topic: string, kind: string, body: Record<string, unknown>): EditRecord | null {
  const full = { authority: "human", ...body };
  return topicBodyRejection(kind, topic, full) === null
    ? { stream: "topics", kind, topic, body: full }
    : null;
}

function bare(text: string): string {
  return text.replace(LIST_MARKER_RE, "").trim();
}

/** The status a status line names, in any view language, with its done day. */
function parseStatus(text: string): { status: TopicStatus; resolved?: string } | null {
  for (const s of STRINGS) {
    const match = new RegExp(
      `^${escape(s.statusLabel)}\\s*:\\s*(.+?)\\s*(?:\\((.*)\\))?\\s*$`,
      "i",
    ).exec(text.trim());
    if (match === null) continue;
    const label = match[1]!.toLowerCase();
    for (const other of STRINGS) {
      const status = TOPIC_STATUSES.find((st) => other.topicStatus[st].toLowerCase() === label);
      if (status === undefined) continue;
      const day = new RegExp(DAY).exec(match[2] ?? "")?.[0];
      return status === "done" && day !== undefined ? { status, resolved: day } : { status };
    }
  }
  return null;
}

function milestoneParts(line: string): { checked: boolean; text: string } {
  const rest = bare(line);
  const box = CHECKBOX_RE.exec(rest);
  const text = (box === null ? rest : rest.slice(box[0].length))
    .replace(MILESTONE_TAIL_RE, "")
    .trim();
  return { checked: box !== null && box[1] !== " ", text };
}

function itemText(kind: TopicItemKind, line: string): { text: string; reason?: string } {
  const rest = bare(line);
  switch (kind) {
    case "decision":
      return { text: rest.replace(DECISION_TAIL_RE, "").trim() };
    case "open-question":
      return { text: rest.replace(QUESTION_TAIL_RE, "").trim() };
    case "log-entry": {
      const text = rest.replace(LOG_HEAD_RE, "");
      const because = BECAUSE_RE.exec(text);
      return because === null
        ? { text: text.trim() }
        : {
            text: text.slice(0, because.index).trim(),
            reason: because.slice(1).find(Boolean)!.trim(),
          };
    }
    case "milestone":
      return { text: milestoneParts(line).text };
  }
}

const ITEM_KEYS: Readonly<Record<string, TopicItemKind>> = {
  d: "decision",
  q: "open-question",
  l: "log-entry",
  m: "milestone",
  mx: "milestone",
};

function itemCorrection(
  topic: string,
  kind: TopicItemKind,
  rest: string,
  before: string,
  after: string | null,
): EditRecord[] | null {
  const parts = rest.split(":");
  const item = parts.at(-1)!;
  const logClass = kind === "log-entry" ? parts[0] : undefined;
  // `mx:<done record>:<item>`: a done milestone, and the record that completed it.
  const doneRecord = kind === "milestone" && parts.length === 2 ? parts[0] : undefined;
  if (after === null)
    return [human(topic, kind, { item, removed: true })].filter((r) => r !== null);
  const now = itemText(kind, after);
  const was = itemText(kind, before);
  const out: Array<EditRecord | null> = [];
  if (now.text !== was.text || now.reason !== was.reason) {
    out.push(
      human(topic, kind, {
        item,
        text: now.text,
        ...(logClass !== undefined ? { class: logClass } : {}),
        ...(now.reason !== undefined ? { reason: now.reason } : {}),
      }),
    );
  }
  if (kind === "milestone") {
    const wasDone = milestoneParts(before).checked;
    const isDone = milestoneParts(after).checked;
    if (isDone && !wasDone) out.push(human(topic, "milestone-done", { milestone: item }));
    // Unticked: the user takes the completion back.
    if (wasDone && !isDone && doneRecord !== undefined) {
      out.push(human(topic, "undo", { record: doneRecord }));
    }
  }
  if (out.some((r) => r === null)) return null;
  return out as EditRecord[];
}

function one(record: EditRecord | null): EditRecord[] | null {
  return record === null ? null : [record];
}

/**
 * The topic records for the keyed line `key`, reworded from `before` to
 * `after` or deleted (`after` null); `null` when the key is not a topic
 * line this module maps, or the new text does not make a valid record.
 */
export function topicCorrection(
  key: string,
  before: string,
  after: string | null,
): EditRecord[] | null {
  const match = KEY_RE.exec(key);
  if (match === null) return null;
  const [, topic, what] = match as unknown as [string, string, string];
  const [head, ...tail] = what.split(":");
  const rest = tail.join(":");
  switch (head) {
    case "title": {
      // A deleted title is rendered again; the topic keeps its name.
      if (after === null) return [];
      return one(human(topic, "topic-rename", { title: after.replace(/^#+\s*/, "").trim() }));
    }
    case "desc": {
      if (after === null) return one(human(topic, "topic-rename", { description: null }));
      const text = after.trim();
      if (STRINGS.some((s) => s.topicNoDescription === text)) return [];
      return one(human(topic, "topic-rename", { description: text }));
    }
    case "status": {
      if (after === null) return [];
      const parsed = parseStatus(after);
      return parsed === null ? null : one(human(topic, "topic-status", parsed));
    }
    case "goal":
      return one(human(topic, "topic-goal", { goal: after === null ? null : after.trim() }));
    case "gp": {
      if (after === null) return one(human(topic, "undo", { record: rest }));
      const proposal = GOAL_PROPOSAL_RE.exec(bare(after));
      const goal = proposal === null ? bare(after) : proposal.slice(1).find(Boolean)!.trim();
      return one(human(topic, "topic-goal", { goal }));
    }
    default: {
      const kind = ITEM_KEYS[head!];
      return kind === undefined ? null : itemCorrection(topic, kind, rest, before, after);
    }
  }
}

/** The section an anchor key sits in, as the kind of item a line added there becomes. */
function sectionOf(what: string): TopicItemKind | null {
  const [head, ...tail] = what.split(":");
  const name = head === "a" && tail[0] === "h" ? tail[1] : head === "h" ? tail[0] : null;
  if (name !== null) {
    const bySection: Readonly<Record<string, TopicItemKind>> = {
      milestones: "milestone",
      decisions: "decision",
      questions: "open-question",
      resolved: "open-question",
      log: "log-entry",
    };
    return bySection[name ?? ""] ?? null;
  }
  if (head === "gp") return "open-question";
  return ITEM_KEYS[head!] ?? null;
}

/**
 * The item id of a line the user added: derived from the topic, the
 * section and the text, so the same line added in two copies of a page (a
 * sync tool's conflict copy beside the page) is one item, not two.
 */
function additionId(topic: string, kind: TopicItemKind, text: string): string {
  return `u${sha256Hex(`${topic}\u0000${kind}\u0000${text}`).slice(0, 24)}`;
}

/**
 * The topic records for a line the user added below the keyed line
 * `anchor`; `null` when the anchor is not inside an item section of a
 * topic page.
 */
export function topicAddition(anchor: string | null, line: string): EditRecord[] | null {
  const match = anchor === null ? null : KEY_RE.exec(anchor);
  if (match === null) return null;
  const [, topic, what] = match as unknown as [string, string, string];
  const kind = sectionOf(what);
  if (kind === null) return null;
  if (kind === "milestone") {
    const { checked, text } = milestoneParts(line);
    const item = additionId(topic, kind, text);
    const records = [
      human(topic, kind, { item, text }),
      ...(checked ? [human(topic, "milestone-done", { milestone: item })] : []),
    ];
    return records.some((r) => r === null) ? null : (records as EditRecord[]);
  }
  const { text, reason } = itemText(kind, line);
  const record = human(topic, kind, {
    item: additionId(topic, kind, text),
    text,
    ...(kind === "log-entry" ? { class: "note" } : {}),
    ...(reason !== undefined ? { reason } : {}),
  });
  return record === null ? null : [record];
}